Arkiv för ‘Osclass’ kategori

Data Objects for Osclass plugins using dliCore

13 april, 2015

As mentioned in our previous post regarding database tables for Osclass plugins written using dliCore the library offers another way to access the data stored in your tables. It was a thought that originated in an old library I did many years ago that I simplified for this case. The old approach consisted of something I called data gateways. These gateways would fill objects (that knew nothing about the back end storing the data) with data. The objects could be loaded and saved from each back end through the respective gate way. This made it quick and easy to change your code from working with the database to testing using mock-up data in xml files.

For dliCore I took parts of this an made a system that would abstract the database layer for the developer and allow them to work with objects instead. I made it so that it would not require a huge overhead and it would also keep track of the fact that objects and databases were in sync. By that I mean that if you add a column to your table and you don’t allow it to have a default value then it must be present in the object or an exception is thrown.

Here I give a very simple presentation about how to connect an object to a table. Let’s use a simple messages table in a plugin called userMessages in our example.

Create table

First we create our table class.

Our messages contains a id, a foreign key to the receiving user, a foreign key to the sending user, a title, the contents and a date time of when the message was sent. Indexes to speed up access by date etc could of course be added.

Register table

Now we register the table with our plugin to it will be installed when the plugin is installed.

Creating our data object

Now we create an object that extends DbModel. We tell it which table it’s connected to and we give it the member variables needed to carry the data. Note that we could add more variables here than what is available in the table and add additional logic as well.

If a set function is present, that will be used when creating the object when reading from the database. So any extra logic needed on data read from the database can be put there. For instance you might store a data in some specific format in the database but want it to be stored differently within the object. If this need does not exist and there is no wish for any public get or set functions they can be left out.

Functionality to save a single or multiple items and fetch items based on their primary key exists by default. Even multi-column primary keys are supported. To add extended functionality like we did in our old DAO object we can do things like this to our object.

Working with your objects

By these simple steps you can now do things like

Closing thoughts

If one opts-in to use this style you get an easy encapsulation of objects without much work. For the standard tables like User these objects will also be made available by the library. That way, user objects can be passed around instead of user id´s or associative arrays.

Note that just as with most parts of dliCore, the use of these objects are purely optional. You can stick to just creating the tables in this new way, or doing it the old manual way and sticking with DAO your old objects. For older plugins being moved to use dliCore this can help reduce the needed modifications.


Flattr this!

Database Tables for Osclass plugins using dliCore

13 april, 2015

One thing that a lot of plugins wish to do is to save persistent data. This can be done in a number of ways. There are volatile ways like storing them in memory etc and non volatile ones like storing data to files, databases and similar. Since Osclass itself uses the MySQL database (probably works fine with Miranda DB to) a lot of plugins use this to store their data.

As with most things, working with databases has had a “semi official” way established.

Most plugins tend to do things in the following way.

Define table structure

The table structure is placed in a file. This is commonly named struct.sql but could be named anything. Here’s a small mock-up of a table for storing some random extra data for a users profile.

Osclass internally uses prefixes on column names to convey what type of data the column contains.

The comment /*TABLE_PREFIX*/ will be automatically replaced with the prefix defined in the config.php file in the root folder of your Osclass installation.

Some plugins have one table defined in the file, some have several, others have several files with one table in each file etc. For instance our i_data_type column might have a table with mapping between datatype id’s and actual names. However, this could also be mapped in the PHP code.

This file is then read and executed during plugin installations. I have seen several ways, but a common one is to call something like this in the plugins install function


DAO objects

Most plugins then create their own DAO object by extending the DAO class of Osclass. I have also seen examples of plugins doing queries directly in their own functions (often contained in a very messy index.php file… hehe). I would suggest that you at least use the base DAO object in Osclass to communicate with your database since it handles a lot of work for you.

Extending it and making your own class is good if you want to encapsulate functions within it.

If we for example wanted to get the data of a particular type for a given user you could have a function in your DAO object that looked something like this

You would then build up more and more functionality and add more and more functions for what you needed to be able to do with your data.

Something to think about

There are some issues with this approach. Not really problems with Osclass itself, but things people should think about.

Most sites I have visited has has their struct.sql files visible. That means that anyone could type in the url to the struct file and view the layout. This could then be used to identify potential ways to compromise the site. Since most plugins use this common approach and naming scheme it’s quite easy to locate schema files to view. You could “fix” this by editing your .htaccess file to not allow .sql files to be viewed. Something lite this should work.

Also, passing data around as associative arrays makes it easy to introduce errors that go unnoticed until code is in production. If you use an IDE that gives you nice warnings about typos in function names etc, make sure you type your array keys correctly since it will not report errors in those 🙂

How you could do it using dliCore

Since dliCore is all about encapsulating things and streamlining there is functionality in place to handle databases to. Instead of manually adding code to a plugins install and uninstall function to read and execute code to install the needed schemas dliCore let you define tables as classes.

Defining a table in dliCore

Our previous example table in a plugin named extendedProfile would be created something like this.

Note that most look the same. But we use /*TABLE_NAME*/ instead of /*TABLE_PREFIX*/. This is a new option in dliCore that will equate to /*TABLE_PREFIX*/ plus the $_tableName of the table in question. This is mostly for convenience.

Since the struct is now part of the class it’s not visible to a user trying to access it like it could have been in a .sql file.

The AbstractTable base class contains functions to install and uninstall the table. We could add an optional function called updateSchema which will be called if a plugin is updated. It will in that case be passed the previously installed version and the newly installed one.

In that function any alterations to lift a schema to new versions could be carried out.

Registering tables

In order to have your table installed and uninstalled with a plugin (as well as notified when a plugin is updated) you register it with the plugin that is the owner of it. This can be done in your plugins _init function.

The _registerTable function is a member function of he Plugin class and takes either an instance of the table or the class name of the table and an internal name. Using the class name makes sure that no instance is created until it’s needed.

Any table registered with a plugin has their installSchema function called when the plugin is installed and their uninstallSchema function called when a plugin is uninstalled.

So adding a table to a dliCore based plugin is a matter of creating your table class like above and registering it with the plugin. The rest is done for you.

Accessing data

Note that we didn’t create any functions to access the data in our table class like we did in our DAO object. You could do this if you want to. As with most things in dliCore it’s optional to use features or stick to the old school way of doing things. But another way to access and work with data objects is to use the dliCore dbModel class. I will talk more about that next time.

Flattr this!

Streamlining, accelerating and encapsulating Osclass plugin development

12 april, 2015

In our previous post we looked at the basics of building a plugin for Osclass. There are however quite a few issues that I have observed in almost every plugin I have looked at that I felt I wanted to do differently.

Issues I saw with plugins

  • index.php often becomes bloated with functions that handle every aspect of the plugin. At rare occasions are classes that separate logic and presentation introduced (I did this myself when usign the official way of constructing plugins), but more often than not index.php will just consist of a myriad of function mixing logic and presentation, acting as functions for hooks and so on and so fourth.
  • All functions in index.php are publicly available. That means that for plugins that ended up having all their function in index.php, any one of these functions would be publicly available to call from any other plugin.
  • More often than not hooks will be riddled with html code, javascript together with switch and if statements.
  • Plugins are not naturaly object oriented.

Now, you can solve a lot of these issues on your own and some things are not even problems to some people. Object Oriented development might not be your cup of tea and in that case you will not have the same issues I have with this. But to me Object Oriented development is a great way to encapsulate functionality. For instance for a Plugin.

I have for example introduced classes that actually handle my logic and presentation that were basically just called from the hooks in my plugin. But as time went on and I noticed I did more than the few plugins I originally thought I would be doing I felt I wanted some base for my plugins and not reinvent the wheel every time.

Streamlining, accelerating and encapsulating Osclass plugin development

I decided to build myself a base library that I could use to quickly create new plugins. I created dliCore which consists of two components. It’s all just a few days old so things could change, but here’s some of the basics of what I want to achieve.


dliCore is a plugin in itself. It provides admin interfaces to configure common things that all plugins based on dliCore can take advantage off.

  • Configuring things like caching manager
  • Presents common place for support requests regarding plugins built using dliCore
  • Contains dliLib and makes sure that is available to plugins


  • Contains a myriad of classes to support development of plugins

Together they present developers with a base that accelerates development of plugins and keep them organized even when they grow to large proportions. Do note that any part of it is optional. There are functionality to link objects to specific database tables, but a developer is free to create an Osclass DAO object and work with that if they want to.

This was primarily meant for my own plugins and could function as a catalyst for others to create their own solutions. But if there is a desire for others to use this I’m open to a public supported release to help all of my fellow plugin developers.

Building our Osclass Hello World plugin using dliCore

With dliCore I wanted to take a more object oriented approach and encapsulate plugins in a more clear manner. Instead of having your index.php file contain a bunch of public functions, all which are loaded, mixed logic and presentation within these functions etc. dliCore allow you to encapsulate all of your plugin functionality within a Plugin object. This makes the index.php file look a bit different.

First we define a namespace for our plugin. These further help us keep our plugin specific code isolated.

A good convention is to have the name of your plugins folder, the namespace and the name of the plugin be the same.

After that we have our normal info block.

I would have liked to be able to include this in the plugin class itself, but due to how Osclass reads that data it’s not possible. I wanted to make sure no alterations were needed to Osclass in order for dliCore to work.

Next we declare that we will be using the PluginManager and our plugin dliTestPlugin.

After that we check that dliCore is enabled. If it is we make sure that the index.php file of dliCore is loaded by a require_once (since we can’t force Osclass to load that before any other plugin) create an instance of our plugin and register it with the PluginManager. If dliCore is not enable we register a install hook that will just tell the user that dliCore is needed for this plugin to work.

Now you might look at this and go

-“But hey, if dliCore is enabled we don’t register any install hook. So we won’t be able to install our plugin… and there’s no uninstall hook either… and…”

Easy there. As I said, everything is encapsulated. We do have install functions and uninstall functions and all the other stuff to. They are just not globally available.


Let’s take a look at our plugin class

Here you can see that our plugin contains two public function. installHook and uninstallHook. These are the functions that will run when the plugin is installed or uninstalled. It actually also automatically handles a lot of other things in the background during installation and installation as well, but we’ll look at that later.

Hooks using dliCore

dliCore makes it super easy for you to add a hook to your plugin. Simply create a public function, name it correctly and you have a working hook.

Registering a hook for the item_detail hook

Registering a hook for the before_html hook

As you can see, you use the normal hook name you want to hook against and write that name in camel case instead of using underscores and then you end the name with Hook.

The exact same behavior  is available for filters, just en the function name in Filter.

How do we handle that routing thingy to show our file helloWorld file?

Using dliCore you are free to setup routes like normal in for instance the _init function of your plugin or even the index.php file. But that would make me a bit sad.

Instead you should use Controllers. Create a subfolder under your plugin and name it Controllers. Insede we create a file HelloWorldController.php.

This controller will handle our logic. That way we can easily keep it separated from the presentation.

By adding an Action function to your controller, dliCore will automatically create the needed routes for it. For instance the route dliTest/HelloWorld/helloWorld will run our helloWorldAction function in our HelloWorldController. All that is done for you.

But we passed a message parameter last time. How do we get the route to understand that it should accept a parameter named message? Well, you simply add it as a paramater to the action function.

This will automatically add to the route that a parameter called message is accepted by the route and will automatically provide your function with the result of that. But how do we make sure the parameter fulfills a specific regexp like we could when we manually crafted our routes? Well, I could have used some array to map function parameters to their regexps etc, but I wanted to keep it all in one place. One place to update if you wanted to add or remove a parameter. At first I was thinking about letting the user provide the regexp in a comment block. But I didn’t really like that. After scratching my head a bit I came to think about the fact that since actions are automatically called I could hijack their default value and use that to convey their regular expressions.

So in order to make sure it’s only valid to pass the characters a-Z to the function, we update it like this.

This means that adding and removing parameters from actions is extremely fast and easy and you only have to alter code in one place. Instead of having to change your function, update your route etc.

Displaying our message

You could very well just echo your message in the action.

That would print our message in a otherwise empty page. This works alright if the response is some JSON etc. But for presentation of normal pages that’s not how I like to do it.

Instead we create a view file. This is our graphical representation file from a request to our given function. So for dliTest/HelloWorld/helloWorld, which ends up running the helloWorldAction function of the HelloWorldController object we create a file named helloWorld.php.

Now we place this file in a sub folder of our plugin views\HelloWorld\helloWorld.php.

The views folder is the top level folder for our views files. HelloWorld is the name of the controller so that all files owned by a given controller can reside in the same place. The helloWorld part of our files name is the name of the action function minus the Action part. That way it’s easy to quickly find a given view file for any action in any controller.

To make it possible to access our message parameter in the view file we export it to the  view.

Then in our view file we write

This will echo our message parameter.

In your view file you could now easily add html markup to style your presentation, without having it mixed with all your logic.

Theme specific views

It’s also possible for you to create theme specific versions of your views. This allows a developer to add support for specific themes or for users to add alterations to specific themes themselves.

To add a theme specific version of a view file, add a folder under the views folder and name it according to the themes name and place your views under that. For instance


Any file placed in the sub folder of an active theme that matches a given route will be used before the default view is used.

The default views can be copied and used as a starting point.

Extra features

dliCore contains a myriad of extra functionality connected to database table management, memory usage, caching, handling objects, managing and sending emails etc. More on this in future posts.


dliCore will be uploaded to the Osclass market so it can be easily installed for any plugin requiring it.


Flattr this!

How to develop Plugins for Osclass

12 april, 2015

As described in my earlier post, Osclass is a free, open-source, web application written in PHP for classified ads. One of the strong sides of it is that you have the options to create and install custom plugins to extend and alter the behavior of the application. There is an integrated market where existing plugins can be easily downloaded and installed. Here are some of my own creations (more are being updated and are on the way).

I started by creating plugins for my own personal use. Since I was the only one using them I often left configuration options in configuration files instead of building full fledged admin interfaces.

But as time went by people started asking me if they could have a copy of different plugins I had made. This would require me to add functionality to them to make them easily managed by other people. Often people who weren’t developers.

One thing that struck me when I was writing new plugins was the official way that they are to be written which I thought had several issues. Since I never thought I would make many plugins, and especially not any released ones, I swallowed my pride and stuck to their regime. But now when I found myself planning more plugins I felt I wanted to streamline the experience of creating plugins for Osclass.

Bellow I will walk you through creating a very simple plugin using the official way. Later I will describe the ideas I have come up with to further streamline and isolate the plugins. The plugin we will be building will be a simple Hello World type plugin with the added option that we will dynamically set the message to show the user.

File structure

To create a plugin you first create a folder under the oc-content/plugins folder, you can call it whatever you want. Within that folder you will need to place at least one file, index.php. That is basically the only requirements regarding the file structure. You could add several files and libraries, java script files, css files etc.

Conventions and guidelines

Due to the fact that functions in your index.php will all be public, you do best in choosing a prefix that ensures that your function don’t end up having the same name as any other function. If your plugin would contain a function install() and another plugin would do the same you would run into problems. Whatever convention you choose to pick your prefix is up to you. But prefixing with some developer identifier and/or the plugin name is one way to go.

Later when we look at my alternate way of writing plugins we will see how we can pretty much circumvent this issue altogether.

Information block

Each plugin in Osclass will have a information block in their index.php file. Here’s an example of ours. More options exist and depending on your plugin not all will be needed.

This information is used internally by Osclass and is for example presented in the admin interface.


  1. Plugin Name
  2. Link to Support URI
  3. Description
  4. Version
  5. Author with link to Author URI
  6. Link to Plugin URI

Make your plugin installable

To make it possible for a plugin to be installed you have to add a piece of code to your index.php file.

What this does is basically to register our plugin as being able to be installed and when a user chooses to install our plugin Osclass will run the function dliTest_install which we don’t have yet. So let’s add that to our index.php. In the same way we can add a function to be run when our plugin is uninstalled by a user. So we’ll go ahead and do that to.

Now we are able to install and uninstall our plugin, although it won’t actually do much.


Osclass uses the concept of hooks to enable you to hook in different parts of your plugin to be run at different points during the applications execution.

The normal syntax for registering a hook is

Our call to osc_register_plugin in order to make it possible to install our plugin is actually just a special case for registering a hook to handle the installation. But it also handles some other functionality and is therefore wrapped in its own function.

As you can see the uninstall function above is registered using the normal osc_add_hook() function, although it does have a bit of a special syntax where the name must be the your_plugins_folder/index.php.

There are a ton of hooks you can use. For instance there are hooks that run in the page header, in the page footer, when the user is visiting an item page, when a new item is posted etc.

Look here for a complete list of hooks.

So a hook has a name and you supply it a function name. Then it makes code your have written in your plugin run at specific places in the application execution flow. This might look very magical, but it’s actually quite easy. When you register a hook the function name you have provided is added to a list of functions to run when the hook with that name is run. It’s basically like providing it a function pointer, but since php gladly executes a function in a multitude of ways you simply have to store the name of the function to run.

For example these are all valid in php

Osclass then simply run a function at specific places that run a given hook.

Now all functions registered to the header hook will be run at that place.

Common uses for this is to add things top the html header, like tags, loading scripts etc. Or hooking in and altering forms such as search and the form to post new items.

Deciding what runs when

One of the problems of the hooks is that there is no real way of telling when in the queue of functions to run your specific function is. It could be that it’s very important that you run your code early, before other plugins have been able to run their functions for the same hook. To help facilitate this you can pass an optional third parameter to the osc_register_hook function. The third parameter will let you set the priority on a scale between 1 and 10 for the function you just registered. But do note that a registered function that has the same priority would make it hard for you to know for sure that your function will be the first to run.

Without knowing for sure I would guess that if two functions have the same priority and register for the same hook, the one registered first will run first. The one registered first will be the one owned by the plugin that was loaded before the other one. And the order in which the plugins load is very likely to be dependent on their alphabetical sorting of their directory name in the oc-content/plugins folder.

So PluginA would load before PluginB and if PluginA registered foo to run at the hook header and PluginB registered bar to run at the same hook and they both had the same priority set, foo would most likely be run before bar.

Make our plugin print something

Many plugins simply make use of existing hooks to output at specific places. For instance, to make our plugin write something when we look at the details of an item we could use the item_detail hook. This hook run at the middle of item’s detail page. $item is passed as argument and can be used if needed.

But what if we want to our plugin write Hello World in a page we have designed ourselves. In order to do that we will have to complete a couple of more steps.

Creating a route to our file

A route is basically a way for you to tell Osclass that

This url should present the user with this file

To do that in Osclass we use the function osc_add_route(). Read about it more on Using routes with Osclass.

So, let’s add a quick route to a page called helloWorldPage.php and make the route accept a parameter names message consisting of characters between a-Z. I will name the route similarly to the actual file, but this is in no way needed.

Link to our new route

Let’s create a href link in the footer of the page to our new route.

To do that we register a hook to run a function that will print our link. In order to get the actual url of our route we use the function osc_route_url(). To that we can also pass an array of values so here we decide what our message variable should be.

Display our message

If you refresh you site now you should see a link in your footer. But clicking it won’t quite take us where we want yet, we first have to create our helloWorldPage.php file. Save it in the same folder as your index.php file. Here we extract the message parameter sent using the Params object and echo it.

Now you will be able to click the link and be taken to the page showing your message.

Complete listing



Closing thoughts

This was a very simple plugin but the basic is the same even for larger plugins. You will end up with more hooks, more files and more routes. But this is what almost every plugin looks like. But keeping it all neat and easy for others to comprehend becomes quite hard when the plugins grow. We will look into this problem and how we can solve it in the next post.

Flattr this!


28 mars, 2015



I often find myself writing all kinds of systems for my own, and other peoples, needs. But when I decided to make a classified site some time ago I had a clear idea of the functionality I wanted in it. But with a full time job as a Systems Engineer, plenty of personal projects and freelance things going, a family with child number three on the way and a decision to start working out to be able to keep up with my kids I felt that it would take me a long time to write what I wanted from scratch.

Instead I started looking for possible existing systems that could fit my needs. After a few tested systems that didn’t live up to my needs I stumbled across Osclass.

Osclass is a free, open-source web application for building classified ads style sites. It includes a comprehensive admin interface and more importantly, a plugin system that allowed me to add and change the behavior to suit my needs. The internal design seems inspired by WordPress and there are plenty of plugins and themes available to make it fit your ideas.

From a Systems Engineer perspective there are things I don’t really like, but it is still one of the best open-source alternatives around. On top of that the team quickly iterates and updates the application. Both to quickly fix identified security issues and to add new functionality.

Get Started

Step 1: Download
To launch your osclass classifieds site in just a few minutes,
download the lastest release and unzip the folder.

Download now

Step 2: Upload

Use an FTP program like FileZilla to upload the folder’s
content to the root of your server’s hosting.

Osclass, the free classifieds script

Step 3: Install

Go to your website within your browser. Follow the instructions,
and you’ll be up and running in no time!

Bonus: Customize

Have a look at available templates & plugins to customize
your site and add even more functionality.

Install Osclass with A2 Hosting

Install your Osclass faster than light with A2 Hosting! Just follow these simple steps. Have your Osclass running with no effort and in less than 2 minutes!


The above video is one of several official tutorials produced by the Osclass team. Check out the rest of their great tutorials to learn every aspect of Osclass

Extend, adapt and create the site you want!

Through the flexible plugin and theme support you have every option to build the site you envision. Even if the default theme (called Bender) is quite dull, there are a ton of really cool ones available. The admin interface offers a lot of customization options and also tracks some basic statistics displayed in easy to view graphs.

If you miss some functionality check out the official market. There are plugins to extend item attributes, provide additional security, personal messaging systems, payment option etc. If you don’t find what you need on the market you can develop your own functionality. Here’s a some very rudimentary documentation about creating plugins. I plan a larger article regarding this where I will also talk a bit about the things I like, and the things I personally decided to do in another way. If you don’t feel comfortable developing your own plugins you are welcome to contact me.

Some of my plugins

Bellow is a link to some of my plugins. Most of my earlier ones that were written for myself didn’t contain fancy admin interfaces. But after other people started asking me to use my plugins I have started to update some of them. That is also what made me come up with some ideas on making plugins that I feel streamline the process a bit. More on that in a later post.

My plugins in the Osclass market

Flattr this!