-
Notifications
You must be signed in to change notification settings - Fork 195
Custom
The custom directory is so that you can easily extend the base open source install of Unmark. You can easily overwrite models, controllers, routes, etc. All you need to do is mirror the directory and files you want to override from the /applications folder. The custom loader will check under /custom for the file first. If found, use that. If not move to /application folder. So if you want to load anything custom please create a /custom folder.
Any config/route files will load both. Meaning if you redefine /custom/configs/routes.php, the loader will load the application version first and then your custom one. That way you can just overwrite or add what you need to configuration files and not have to redefine the entire file.
If you want controllers, models or libraries to extend application version just make it so. If you rather they extend the base CI_Controller you can do that too.
The core application has default routes. If you wish to change these routes or add new one you can by adding a routes.php file to your /custom/config folder. If you are using ENVIRONMENT folders in configs you can do that as well, IE: /custom/config/development/routes.php.
You don't need to redefine every route, just create your own routes file and add or update the routes you need. The core application's routes load first, then the custom routes. So you can keep the application routes, change a few of them, add new ones or a combination of all those.
/custom/config/routes.php
/custom/config/{ENV}/routes.php
Autoloading works just like routes except nothing in the default autoload file is overwritten. The application itself needs items to load automatically, if you custom app does, just create your own autoload file under /custom/config/autoload.php. You don't need to redefine anything in the core one, just add what you need. We will merge the two files at runtime.
/custom/config/autoload.php
/custom/config/{ENV}/autoload.php
Configs work the same way as routes. We load the core application's configs first then any custom ones. This way you can override, add or append other items to existing application configs. Let's say your application was adding a new error code. The core application has these defined in /application/config/all/app.php. You want to add error code 702 for Random error. Simply create custom/config/all/app.php and add $config['error_codes'][702] = 'Random Error' and it will be appended to the existing error codes.
It knows if it should append or overwrite a config. If you need to load any custom configs just for your application please add them to your autoload file.
/custom/config/{CONFIG}.php
/custom/config/{ENV}/{CONFIG}.php
Hooks are already enabled by default. If you want to add any hooks to your custom app simply add them to /custom/config/hooks.php just as you would for a default CodeIgniter install. After that just place your files in /custom/hooks folder and you should be set.
/custom/config/hooks.php
/custom/hooks/{FILE}.php
You can add your own migration files as well. In order to try and limit merge conflicts we have updated the naming convention of migration files from NNN_Migration_name.php to YYYYMMDDHHIISS_Migration_name.php. You should use the latter. This way it will limit the amount of conflicts you get when you download a new core version of Unmark that has new migrations.
/custom/migrations/YYYYMMDDHHIISS_My_Migration.php
In order to run this you will have to define your own migration config.
Path: /custom/config/migration.php
Code: $config['migration_version'] = {MIGRATION_NUMBER};
We will figure out who has the newest migration file (core or custom) and set that as the current latest migration.
Now run the update:
$ php index.php migrations latestYou can redefine any of the core application's files just by placing them in the same folder structure and file name in your custom folder. If you do this for any of the above it will be loaded instead of the application's. This way when we update the core application you don't end up with bunch of merge conflicts.
/custom/helpers/{NAME}_helper.php
/custom/libraries/{LIBRARY}.php
/custom/models/{MODEL}.php
You can use folders just like you would in default CodeIgniter or place files directly in the folder.
/custom/controllers/{CONTROLLER}.php
/custom/controllers/{FOLDER}/{CONTROLLER}.php
You can use folders just like you would in default CodeIgniter or place files directly in the folder.
/custom/views/{VIEW}.php
/custom/views/{FOLDER}/{VIEW}.php
By default the app caches nothing. We leave it up to you on how you want to cache items. The system itself will attempt to cache SQL results in the models (we don't cache full pages), but if you don't have a custom cache library defined nothing will happen.
To add you own custom cache library, simply create a new class called Cache under /custom/libraries/cache.php. We will look for this file, if found we will create a new cache object and send you the arguments. From there you can do as you wish with the data.
You have to use some standard method in order to use your own cache. The are defined below with the acceptable arguments. Don't worry if we call a method that doesn't exist in your custom library, we just skip it. It won't error out.
Used to add a new item into cache.
| Variable | Type | Default | Required | Description |
|---|---|---|---|---|
| $k | string | N/A | Yes | The unique key for the cache item. |
| $v | mixed | N/A | Yes | The value to save. |
| $override | boolean | false | No | Set to `true` to always save the cache item no matter if it is expired or not. |
Takes the key submitted an attempts to delete an cache item. Wildcards can be submitted as the last character to match all items that start with 'x'.
| Variable | Type | Default | Required | Description |
|---|---|---|---|---|
| $k | string | N/A | Yes | The key to search for and delete from cache. |
Reads the value of a cache key if not expired. If expired or not found, it will return false.
| Variable | Type | Default | Required | Description |
|---|---|---|---|---|
| $k | string | N/A | Yes | The key to return the value for. |
Want to track application errors to a 3rd party service? No problem. Just follow the steps below and we will send all the errors and exceptions found to your custom error tracker and you can do what you please with them.
- Add a library called
Error_Trackingto/custom/libraries/. The file name should beError_Tracking.php. - Set up a constructor to accept one parameter that is an array
- We will pass all the error information to your library if found when it is loaded.
- When received, you can do anything you want with the info
We send an array full of error/exception information. We also send the raw exception object when it is present so you have access to that as well. The info is as follows (this example uses $params as the array name):
All variables should be checked for before they are used, just so your application can remain sane :).
| Key | Description |
|---|---|
| $params['backtrace'] | Array full of backtrace information (file, line number, etc). |
| $params['custom_data'] | Array of any custom key/value pairs sent by the application. |
| $params['enviornment'] | The current enviornment. |
| $params['exception_object'] | If there is an exception object present we will send the raw object across as well. |
| $params['message'] | Error or exception message. |
| $params['type'] | The type of error or exception (IE: E_ERROR). Exceptions just say 'Exception'. |
| $params['user'] | Array of the current user's information (minus their encrypted password). |
If errors happen on the development enviornment (if you have one), it will not use the custom tracker. It will then log all issues to the CI default log files only.
So we have a library called Exceptional and we overwrite CodeIgniter's CI_Exceptions with Plain_Exceptions. All errors/exceptions end being filtered to the Exceptional class outside of dev. From there it checks if you have the Error_Tracking.php file in your custom folder. If you do it loads it and sends the information above over for you to do as you wish.
If this file does not exist it simply logs the same information to your default CodeIgniter log file. If this happens we scale back the backtrace a lot to just show the last file it stopped at instead of the full stacktrace.
You can also override any static assets using your custom folder. In order to do this you must be using either apache or nginx (you can use something else but you are on your own for the configs). If using Apache there is already a .htaccess file in the /assets folder that will look for a match in your /custom folder. If found it uses it, if not if uses the original file.
For nginx you can use this small configuration:
location /assets/ {
try_files /custom$uri $uri =404;
}
Apache .htacess if using this:
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{DOCUMENT_ROOT}/custom/%{REQUEST_URI} -f
RewriteRule ^(.*) /custom/assets/$1 [L,QSA]
</IfModule>
If you are loading any custom files, then you need to load them either in your custom application or in yoru autoload file. For custom controllers, you will need to add a route when applicable.
It's wise on your part to add any level of security you wish. Below are a few methods:
Add this to the top of every file in the custom directory.
<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');Deny from all
location ~* ^/custom {
deny all;
}