Automatic Update

When a new update is available, you'll get a notification in your Admin Notification bar. Click on that button and osclass will follow with the automatic upgrade.

Manual Update

These are short instructions, we're going to extend them in the future. If you experience problems you should report them on Osclass forums.

For these instructions, it is assumed that your Osclass URL is http://example.com/.

Step 1: Take a backup

You should take a backup of your database and files. All your data is held in the database, so you will need to have a copy just in case you change your mind after upgrading and need to go back. The same reasons are sustained to make a backup of oc-content folder.

Step 2: Replace Osclass files

• Get the latest Osclass. (zip or tar.gz)

• Unpack the zip file that you've downloaded.

• Using FTP or you SSH, upload the new files. You should replace all the old Osclass files with the new ones: oc-admin and oc-includes directories and sub-directories, and in the root directory (ajax.php, contact.php, index.php, item.php and so on). Do NOT delete them config.php file.

• Be careful when copying the oc-content directory. You should make sure that you only copy the files from inside this directory, rather than replacing your entire oc-content directory. If you have customized the default theme without renaming it, make sure not to overwrite those files, otherwise you will lose your changes. (Though you might want to compare them for new features or fixes...)

Step 3: Update your installation

If you have permalinks enabled, you should disable them before updating Osclass. Then, update your installation. Just enter to the oc-admin (http://www.example.com/oc-admin/) and it will appear a button to update your database if it's necessary.

Visit http://www.example.com/oc-admin/index.php?page=upgrade&action=upgrade-funcs. If a database upgrade is necessary, Osclass will update your database to be compatible with the last code. If some new values in t_preference are necessary, it will update too.

Final steps

Your update is complete. Remember to activate permalinks if you have disabled theme before. It wasn't too difficult, was it? If anything goes wrong, you should let us know.

Installing new locations

Via Admin panel

Under General Settings > Locations you could install new locations (countries, regions and cities).

Manually

Installing new locations could be a very-long process due to the big amount of data being transferred. You could raise your max_execution_limit on the PHP.ini file or install new locations manually.

• Download the .sql you want to from our GitHub Repository

• Change /*TABLE_PREFIX*/ for whatever your prefix is. (If using the OSClass' import functionality it's not needed to modify anything)

• Import it to your database (via OSClass' import system -Admin panel > Tools > Import-, phpMyAdmin, command line,... )

What is Osclass?

Osclass is a free and open script to create your advertisement or listings site.

Best features: Plugins, themes, multi-language, CAPTCHA, dashboard, SEO friendly.

Clone the repository and the submodules.

$> git clone --recursive git@github.com:mindstellar/Osclass.git

Project info

• Source Code: https://github.com/mindstellar/osclass

• Support Forum: https://osclass.discourse.group , https://osclasscommunity.com/community , https://www.valueweb.gr/forums/osclass/

• Releases: https://github.com/mindstellar/Osclass/releases

• Osclass Extras: https://github.com/mindstellar/Osclass-Extras

• License: [GPLv3]

APC / APCu

You need to edit your config.php file and the following line

   define('OSC_CACHE', 'apc');

MEMCACHE

You need to know ip and port of the machine/s where memcached service is installed and then add the following lines to the file config.php

   define('OSC_CACHE', 'memcache');
   $_cache_config[] = array(
       'default_host'      => '127.0.0.1',
       'default_port'      => 11211,
       'default_weight'    => 1
   );

Coding Style

This small guide is partly based in the coding style guide of Zend Framework : http://framework.zend.com/manual/1.12/en/coding-standard.coding-style.html

PHP Code Demarcation

PHP code must always be delimited by the full-form, standard PHP tags:

<?php
 
?>

Variables

Variables should follow the Hungarian Notation ( https://en.wikipedia.org/wiki/Hungarian_notation ), that means they should start with a character indicating the type of variable, for example i for integer, a for arrays, o for objects, s for strings ... Also, each first character of a word should be uppercase.

$iThisIsAnInteger = 42;
$sSomeText = 'This is some text';
$aVariable = array(1, 2, 3, 4 , 5);
...

Note: SQL column's names should follow a similar notation, but the first character should follow an underscore. Words are separated by an underscore, all in lowercase. If the column is a primary key, it should be preceded by "pk_" if it's a foreign key by "fk_"

i_integer_variable
s_some_text
dt_registration_date
pk_i_id // this is a primary key
fk_i_category_id // this is a foreign key
...

Classes

Class Declaration

The brace should always be written on the line underneath the class name.

Every class must have a documentation block that conforms to the PHPDocumentor standard. The following is an example of an acceptable class declaration:

/**
* Documentation Block Here
*/
class Foo
{
    /**
     * Documentation Block Here
     */
    public function bar()
    {
        // all contents of function
        // must be indented four spaces
    }
}

Control Statements

If/Else/Elseif

Control statements based on the if and elseif constructs must have a single space before the opening parenthesis of the conditional and a single space after the closing parenthesis.

The closing brace is always written on its own line. Any content within the braces must be indented using four spaces.

if ($a != 2) {
    $a = 2;
} else {
    $a = 7;
}
 
if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
    $a = 4;
} else {
    $a = 7;
}

The following if statements is not valid

if($a != 2)
    $a = 2;

Switch

Control statements written with the "switch" statement must have a single space before the opening parenthesis of the conditional statement and after the closing parenthesis.

All content within the "switch" statement must be indented using four spaces. Content under each "case" statement must be indented using an additional four spaces.

switch ($numPeople) {
    case 1:
        break;
 
    case 2:
        break;
 
    default:
        break;
}

Documentation Format

All documentation blocks ("docblocks") must be compatible with the phpDocumentor format. Describing the phpDocumentor format is beyond the scope of this document. For more information, visit: » http://phpdoc.org/

More information

This small guide is partly based in the coding style guide of Zend Framework : http://framework.zend.com/manual/1.12/en/coding-standard.coding-style.html

Increasing memory allocated to PHP

Released with version 2.3, the OSC_MEMORY_LIMIT option allows you to specify the maximum amount of memory that can be consumed by PHP. This setting may be necessary when you see a message such as "Allowed memory size of X bytes exhausted".

This setting increase PHP memory for OSClass, so it wouldn't affect other applications. By default, the memory allocated is set to 32MB. If PHP has been allocated 128MB, there is no need to set this value to 128M because OSClass checks if PHP has been allocated more memory than the entered value.

This setting may not work if your host doesn't allow for increasing the PHP memory limit. In that case, contact your host to increase the PHP memory limit.

Increase PHP Memory to 128MB (add this define constant in config.php)

define('OSC_MEMORY_LIMIT', '128M') ;

Setting up a mail server

With Osclass you could configure your email server. Some shared hosting has limited mail servers, you should always check with your hosting company about it before. If you own your own dedicated server you probably know how to set up one, if not, you should perform some searches on the internet (on a linux machine it's enough to install postfix and courier packages).

Configuring Osclass to use your mail server is very easy, we also offer a pre-filled configuration to use with Google mail servers, you should notice Google offers a limited service and your emails could get marked as spam.

Want to see it in action? Check out our video tutorial on How to set up your mail server.

Mail server settings are located on Mail server option, under General Settings

Custom mail server

• Hostname: usually smtp.yourdomain.com but it could be any domain or IP (localhost by default)

• Server port: This is the port where is your mail server (it depends on the protocol: POP3 - port 110, IMAP - port 143, SMTP - port 25, HTTP - port 80, Secure SMTP (SSMTP) - port 465, Secure IMAP (IMAP4-SSL) - port 585, IMAP4 over SSL (IMAPS) - port 993, Secure POP3 (SSL-POP) - port 995)

• Username: This is optional, only in case your server need authentication

• Password: Same as Username

• Encryption: ssl, tls or left blank as possible values

• Check box for SMTP authentication check only if you're sure what you're doing

Google mail server

You need a Google Mail account, assume yours' myname@gmail.com

• Hostname: smtp.gmail.com

• Server port: 465

• Username: your username before the @ ( "myname" )

• Password: your password

• Encryption: ssl

• Check box for SMTP authentication checked

Troubleshooting

I'm not receiving any emails

Check your configuration on the Osclass admin panel. Maybe you have misspelled some detail. If everything looks correct, then check your mail server is working properly. Contact you hosting company or check the mail server's log to know what is happening.

It was working correctly but suddenly it stopped and I don't receive anything

Your mail server has stopped for some reason or you're getting your emails marked as spam. Check your mail server is running and revise its log. If they are being marked as spam, you probably have sent too many emails in a very short time interval.

I have other problems not listed here

Feel free to contact us on our support forums. We will be glad to help you. When posting your question, please, give us as much information as you can, so we could offer you a solution soon.

Using the Enqueue functions

Why use them?

The enqueue functions are used for loading your javascript and css files. The reason they were added is because many plugins make use of javascript frameworks such as JQuery, JQuery-ui, and fancybox just to name a few. There is a high chance that these javascript files could be loaded multiple times and that is where the enqueue functions come into play. The enqueue functions help to reduce the chances of the same file getting loaded more than once.

The Enqueue functions

javascript related functions

osc_enqueue_script($id) - Enqueue script

osc_remove_script($id) - Remove script from the queue, so it will not be loaded

osc_register_script($id, $url, $dependencies = null) - Add script to be loaded

osc_unregister_script($id) - Remove script from the queue, so it will not be loaded

osc_load_scripts() - Print the HTML tags to make the script load

css related functions

osc_enqueue_style($id, $url) - Add style to be loaded

osc_remove_style($id) - Remove style from the queue, so it will not be loaded

osc_load_styles() - Print the HTML tags to make the style load

Good naming practices

If you're going to use another js library/file which is not in oc-load (for example fancybox, or any other jquery plugin) please, use a "good" name.

If you're going to use "Jquery My plugin", do not register it as "my_extrange_name", because if someone else could be registering it with a different name and then it would be loaded twice.

Examples

registering a javascript file

Enqueueing the script

Enqueueing a style

Ok now onto a real life example.

To use these functions you will want to create a function for this example I am going to use ex_load_scripts() please use a unique function name in your plugin if you are planning on releasing it otherwise we could end up with conflicting function names.

Once you add that code you will then need to add the following hook to your index.php file of your plugin.

To load the script on the admin side you would use this hook

That is all that you have to do to get your javascript and css files working in 3.1.+

For theme developers a good example can be found in the head.php file of the modern theme.

Pre registered scripts

Osclass pre registers some of the more common javascript files.

Here is the list of pre registered javascript files.

What is Cron?

Cron is a time-based job scheduler in Unix-like computer operating systems. Cron enables users to schedule jobs (commands or shell scripts) to run periodically at certain times or dates. It is commonly used to automate system maintenance or administration. Osclass has a built-in functionality in case your system has no cron daemon, you could enable/disable it from the admin panel, general settings > cron. It's recommended to read more about CRON on the wikipedia.

It's also recommended to use your system's CRON instead of the built-in functionality of Osclass, since you will get better results with the first one. We use this functionality to run a few jobs as sending email alerts or counting number of items per category.

CRON in Osclass

As said before, we need some 'jobs' to be done from time to time, from sending email alerts, to count number of items per category or allow plugins as sitemap perform other actions.

In an ideal world, every server would have CRON enabled, and you would be able to set as many cronjobs as you want. But because we know that it's not always true, we offer this built-in functionality.

Configure CRON with Osclass

Inbuilt Cron

To use the built-in functionality you need to check the Auto-cron option on the admin panel, under Settings Cron.

System Cron

To use your system's CRON functionality you need to uncheck the Auto-cron option on the admin panel, under Settings > Cron settings.

Cron is only available on Unix or Unix-like system (Linux, OSX, Free BSD).

Most of the web servers out there are running a Linux distribution, so it should be no problem at all. Windows systems have several alternatives to CRON which work in different ways. Usually, you need to SSH your server (access via SSH) and type on the command line/terminal this

crontab \-e

You will enter your "cronjob list" on a terminal editor (usually vi, vim, nano or emacs). Then it depends on the editor to save, close, edit the file itself, etc.

Most hosting companies will not offer SSH access, and those who do it, some of them will not offer you the possibility to modify the CRON, but offer you a workaround via admin panel to do it. For example, Dreamhost (under Goodies > Cron) offers you an "easy wizard" to run cronjobs, but limits to one cronjob per user (via terminal/SSH you have no limits).

We can not provide you with more information since it highly depends on your hosting company/server.

A cron job needs a time interval/time and a command to be executed, something like (really, more detailed on the wiki, I will not talk about the different time options)

\* \* \* \* \* command params

In our case, we want to execute a php file, we need to have installed php-cli or php-cgi versions, which are the executables of PHP.

Well, we need to run the CLI (command-line interface or executable) version of PHP, we need to use the full path (your phpinfo could help you on this, or ask your hosting provider!) then, we need to pass as a parameter or argument the PHP file, use full path again (NOTE: Usually, shared server use the home directory to hold their users and websites, so your path will be /home/your_username/public_html, again, "public_html" is one of the most used folders, but it could be different, as website, yourdomain.com or anything. Also, if you own a private server, your web path is probably /var/www)

Crontab (if you could access ssh)

Access your server via SSH, type

crontab \-e

The whole cron-job should look like this

0 * * * * usr/local/php5/bin/php /home/your\_username/public\_html/index.php \-p cron \-t hourly
0 0 * * * usr/local/php5/bin/php /home/your\_username/public\_html/index.php \-p cron \-t daily
0 0 * * 0 usr/local/php5/bin/php /home/your\_username/public\_html/index.php \-p cron \-t weekly

Set to run at every hour o'clock (path of the PHP executable could be different)

Dreamhost

In your admin panel go to "Goodies > Cron jobs > add new cron job", since Dreamhost only allow you to use one cronjob per user, it's better to use this instead :

wget domain.com/index.php?page\=cron \-O /dev/null

and select "Hourly"

Hostgator

Enter your Cpanel, scroll down to "Advanced", click on "Cron Jobs". If you want to know if there's any error, enter your email.

Enter the following command:

wget domain.com/index.php?page\=cron \-O /dev/null

Select to run "Once an hour (0 * * * *)", and you're done!

Different setups

• Best case scenario

You are able to run one or many cron-jobs. In that case, execute oc-includes/osclass/cron.php in your cron-job 'each hour.'

Remember to uncheck General Settings > Cron > Auto-cron.

• Auto-cron

If you are not able to set any cronjob, don't want to or don't know how to set it, just check

General Settings > Cron > Auto-cron and you're done.

The OSC_DEBUG_DB constant, added in version 2.3, saves the database queries to an array and at the end of the execution the queries are displayed at the end the page. The information saves each query: the sql string, how long that query took to execute, the sql number error and string if there has been some sql error.

The OSC_DEBUG_DB_LOG constant, added in version 2.3, logs the sql queries to a file called queries.log in oc-content. If you want to debug the sql queries of the AJAX calls or cron, you must use OSC_DEBUG_DB_LOG because we can't print these at the end of the page. If Apache doesn't have write permissions, you may need to create the file first and set the appropriate permissions (i.e. use 666).

The OSC_DEBUG_DB_EXPLAIN constant, added in version 2.3, run an EXPLAIN query for each select query and logs the result to a file called explain_queries.log queries. It should be used only during the development of OSClass, themes or plugins to see the performance of the queries. Remember, if Apache doesn't have write permissions, you may need to create the file first and set the appropriate permissions (i.e. use 666).

Improving search

MySQL's full-text search capability has few user-tunable parameters.

For Osclass users, item title and item description have a fulltext index, that do search more effective and speed up.

The minimum and maximum lengths of words to be indexed by default is 4 (4 characters), that means, only words more or equal than 4 will be indexed.

Changing the maximum, minimum limit

If you like to change the minimum and maximum lengths of words to be indexed, you need update your mysql config file.

Rebuilding FULL-Text Index

After this, if you modify full-text variables that affect indexing (ft_min_word_len, ft_max_word_len, or ft_stopword_file), you must rebuild your FULL-TEXT indexes after making the changes and restarting the server. To rebuild the indexes in this case, it is sufficient to do a QUICK repair operation:

Source: Fine-Tuning MySQL Full-Text Search

We don’t like bugs, neither you do. I’ve seen a post in talking about this and I’ve found really interesting. I’m going to reproduce it here:

When you report a bug to us, here’s what happens:

• We read the bug report

• One of us tries to reproduce the bug

• If we can reproduce it, we investigate what’s broken and fix it

• But if we can’t reproduce the bug…

• Often bug reports don’t include enough information. Meaning we have go back and ask for details so we can investigate. If you want to increase the odds we fix an issue, and fix it fast, help us out.

A great bug report includes the following:

1. What were you trying to do?

2. What did you click on or do last?

3. What happened / what did you see?

4. What browser are you using?

5. What version of OSClass?

6. What hosting provider? (And if you know, what version of PHP do they use?)

7. The bug is reported to the right place:

   2. Plugins: Specify the plugin and the version

   3. Themes: Specify the theme and the version

We work hard to have you deal with as few issues as possible, but if you want to improve the odds we can fix your issue fast, please take a extra minute to write a bug report that’s easier for us to use. Thanks.

The OSC_DEBUG constant, added in version 2.3, controls the display of php errors and warnings. If this setting is not defined in config.php, the default value is false.

When the OSC_DEBUG is false, the error reporting level is E_ALL ^ E_NOTICE ^ E_USER_NOTICE. In that case, we're not showing notice and strict php errors. However, if we set the constant to true, the error reporting level is E_ALL | E_STRICT and display_error value is 1.

The OSC_DEBUG_LOG constant, added in version 2.3, logs these errors to a file called debug.log in oc-content. If Apache doesn't have write permissions, you may need to create the file first and set the appropriate permissions (i.e. use 666).

How to install Osclass?

To install Osclass you need to follow these easy steps:

1. Download the latest zip package of Osclass from and unpack it in your web-server root, i.e. public_html directory.

2. Execute the Osclass installation script by accessing index.php oc-includes/osclass/install.php from your browser:

   • If you’ve installed it in the domain’s root directory, you’ll have to go to: http://example.com/index.php or directly to http://example.com/oc-includes/osclass/install.php

   • If you’ve installed it in a subdirectory inside the domain, classifieds, for example, go to: http://example.com/classifieds/index.php or directly to http://example.com/classifieds/oc-includes/osclass/install.php This will lead you to osclass inbuilt installer.

3. Follow Osclass installer instructions:

   • Step 3.1

     Make sure the server has the required permissions to write in the files and directories specified. This will allow you to create a basic configuration file as well as upload images, documents, etc.

   • Step 3.2

     Add your access details to the database. If you haven’t created it yet, the installer will ask for another account with permissions that will allow to do it for you.

   • Step 3.3

     Add the basic installation details and select your classifieds site’s country.

   • Step 3.4

   • Installation finished. Use the automatically-generated password to access your admin panel (example.com/oc-admin).

How to get the latest version?

Do not use master branch for your deployment, it may include untested code. Only use zip file provided in our release section.

Contributing to Osclass

We are glad to hear you want to contribute to the Osclass project. Osclass is an open source solution for your classifieds site, developed by and for its users, like you. There are several ways to help Osclass grow and improve, even if you don't know to code, you could still help Osclass.

Documentation

Documentation is done by everyone who wants to do it! This documentation is available on our public GitHub Repo

Translations

Support Forums

Users' participation and involvement are essential to maintain our support forums.

Currently we do not have any official forums but you can get help at which is an active public forum with active community.

We will update this list here if we found more places where you can actively seek or give support.

Development

Do you know PHP, JS or MySQL? Get involved in Osclass development. Help us write code, add features and fix bugs!

Visit our project and check out our repositories. You can sign in and help us improve our core, themes or plugins. The best way to do this is through “Pull request” and help us fixing bugs by applying changes to the code. For any doubt, look up the help section for any doubt.

Testing Osclass

Even if you don’t know to code, you can also contribute to Osclass. You can help us test the previous releases of Osclass as well as our themes and plugins.

Reporting bugs/suggest features

Tell your friends about Osclass

We will be happy if you tell your friends about Osclass, share a link or display a small banner on your site. More users -> stronger community -> better Osclass!

Donations

Osclass is and will always be free,. Sending money to Osclass developers is another way to support the community. If any theme or plugin makes your life a little bit easier, contact the author and show your support. Sometimes developers just need to hear users are happy to use their plugins/themes.

In version 3.0, we introduced an auto-upgrade system for plugins and themes, along with some neat features. To make your plugins and themes able to use this new feature, you need to use the Update URI param on the description of your creations. The Update URI should be unique per theme/plugin and reply a JSON response with the following format:

s_version: Any alphanumeric string is ok, but we encourage only-numeric ones to be able to check is a version is greater or not than the installed one, preferred A.B.C style, as "1.0.2" or "2.1.0"

e_type: e_type has to be one of these options THEME or PLUGIN or "LANGUAGE"

This diagram could be a bit difficult to understand at first and follow all the relations. To be able to use an interactive version of the same diagram, please use the and follow these steps.

• Download (it's free and cross-platform!)

• Install it and open it

• Select Create EER Model From SQL Script

• Look for your file 'struct.sql (your_osclass_folder/oc-includes/osclass/installer/struct.sql)

• Check Place imported object on a diagram

• Click on Execute, Next, Finish

• Re-arrange the boxes (tables) as you wish

Relations will highlight if you place your mouse over the tables or the relations.

Usually plugin and themes needs to add menus in the Administrator panel for provide access to screens. The best way is adding a menu section in the Administration menu that allows the user to access the screens.

There are some functions for manipulate the Administration Menu.

hAdminMenu helper

Add menu page to Administration Menu.

Add submenu page to Administration Menu page given a menu parent identifier.

Remove menu page from Administrator Menu.

Remove submenu page given parent menu page identifier.

Adding submenus to existings menus

Helpers can add submenus to existing menus, like:Submenu Listings

Examples:

At admin panel since osclass version 3.0, there is a toolbar which is visible around the admin panel, can have shortcuts to actions like: add a new listing, show pending updates, ...

Developers can add to the toolbar whatever they want, with hooks, and calling AdminToolbar functions like add_menu($array)

Example, adding link to frontend

What are the routes for?

You could extend Osclass with plugins, and sometimes you need to create a special page, for example to show more options to your users.

In previous versions, the url will look like:

domain.tld/index.php?page=custom&file=your_plugin/page.php

Which isn't the prettiest url you could see, and also the file path are visible which is not a problem, but it's not good. In 3.2 we added "routes" that will transform that ugly url into a more beauty one, like:

domain.tld/your_plugin_page

They even works with regular expressions to accept variables on the url.

The route functions

To make routes works, we first need to create them:

/**
* $id - Shortname of the route
* $regexp - Regular expression of the url
* $url - Required to be able to create the nice-looking url
* $file - file that will be loaded
*/
osc_add_route($id, $regexp, $url, $file)

Later we just need to get the url:

Later we just need to get the url:

/**
* $id - Shortname of the previously created route
* $args - Optional, only required if your url accept parameters
*/
//For public routes
osc_route_url($id, [$args])

//For routes in the admin panel
osc_route_admin_url($id, [$args])

Examples

Here is an example

// Create route
osc_add_route(
     'dynamic-route',
     'dynamic-route/([0-9]+)/(.+)',
     'dynamic-route/{my-numeric-param}/{my-own-param}',
     osc_plugin_folder(__FILE__).'mydynamicroute.php'
   );
// Show link to it
echo osc_route_url(
         'dynamic-route', 
         array(
               'my-numeric-param' => '12345', 
               'my-own-param' => 
               'my-own-value'
               )
    );

Notes

• Parameters in the $url should be enclosed between "{" and "}", example "{parameter}"

• Parameters should have the same name (case sensitive) in both, osc_add_route and osc_route_url

• Additionally, any file located in a folder called "admin" will be opened in admin panel, but show a 404 error in the public site

Example plugin

An example plugin could be found in github : https://github.com/osclass/osclass-plugins/tree/routes_example