Skip to content
Ultimate Client Manager

Configuration

WhereWhat is thereHow to change it
includes/config.local.phpDatabase connection, the installation secret, and a handful of switches that have to be decided before the database is open.Edit the file.
The config database tableEverything else. Company details, currency, tax rates, email, templates, permissions, payment gateway credentials, theme.The Settings screens in the admin area.

includes/config.local.php is created by the installer and is the only configuration file you ever edit. It is not part of the download, so an update never overwrites it.

includes/config.php sits next to it and holds the defaults. Do not edit that one — it is replaced every time you update. Anything you want to change, define in config.local.php instead. It is read first, and a value defined there wins.

<?php
define( '_DB_SERVER', 'localhost' );
define( '_DB_NAME', 'your_database' );
define( '_DB_USER', 'your_user' );
define( '_DB_PASS', 'your_password' );
define( '_DB_PREFIX', 'ucm_' );

_DB_SERVER accepts a port as hostname:3306 or a socket path as hostname:/var/run/mysqld/mysqld.sock.

define( '_UCM_SECRET', '…64 random hexadecimal characters…' );

Every secure link the application generates — invoice payment links, quote approval links, the address of your scheduled task — is signed with this. The installer generates one for you.

If it is not set, the application falls back to using the installation path, which is guessable on shared hosting. Set a real one. Once set, do not change it: changing it invalidates every link already sent to a customer.

ConstantDefaultWhat it does
_REWRITE_LINKStrueTidy URLs. Set it to false if your server does not rewrite requests — see below.
_UCM_FILE_STORAGE_DIRthe installation folderWhere uploads, backups, generated PDFs and session files are written. An absolute path with a trailing slash. See below.
_UCM_FILE_STORAGE_HREFthe site addressThe web address that corresponds to the folder above. Only needed if you change it.
_DEBUG_MODEfalseShows PHP errors on screen and adds a timing panel at the foot of each page. Useful for diagnosing a problem; never leave it on for a live site.
_DEBUG_SQLfalseAdds every database query to that panel. Only has an effect when _DEBUG_MODE is also on.
_BLOCK_EMAILSfalseStops all outgoing email. Set this on a copy of a live site so that testing cannot mail your real customers.
_CUSTOM_UCM_HOMEPAGEnot setSend anyone arriving at the root of the site to this address instead of the dashboard.
_UCM_HIDE_UPGRADEnot setDefine it to hide and block the built-in upgrade screen. Useful if you manage updates yourself.
_UCM_HIDE_BACKUPSnot setDefine it to hide and block the backup screen.

Setting values from the environment instead

Section titled “Setting values from the environment instead”

If you deploy with a script, or to a platform where writing files is awkward, these environment variables are read before the file: UCM_DB_SERVER, UCM_DB_NAME, UCM_DB_USER, UCM_DB_PASS, UCM_DB_PREFIX, UCM_SECRET, and UCM_CONFIG_LOCAL to point the settings file somewhere else entirely. UCM_DEBUG turns error display on.

By default everything uploaded is stored inside your web space, protected by .htaccess rules. If you would rather have it somewhere the web server cannot reach at all, set:

define( '_UCM_FILE_STORAGE_DIR', '/home/youraccount/ucm-files/' );

Create that folder and make it writable by PHP. The application creates the subfolders it needs. Move your existing files across before switching, or they will appear to vanish.

By default the application produces addresses like /customer.customer_admin/ rather than /?m=customer&p=customer_admin. This relies on the web server sending every request that is not a real file to index.php, which the included .htaccess arranges on Apache.

On nginx, or on an Apache server without mod_rewrite, that does not happen and every link in the application gives a 404. There are two fixes:

  • Preferred: configure the rewrite in your server config. On nginx, route anything that is not an existing file or directory to index.php.
  • Otherwise: add define( '_REWRITE_LINKS', false ); to includes/config.local.php. Links fall back to the query string form, which needs no rewriting at all. Everything works; the addresses are just uglier.

There is no setting for this in the admin area — it has to go in the file, because it is needed before any page is built.

Everything else is in the admin area under Settings. The main areas:

ScreenWhat it covers
System SettingsCompany name and address, the site address, currency, date format, timezone, and the administrator email that system notices go to. Set this up first — it feeds invoices, quotes and every email template.
EmailWhether to use SMTP or the server’s own mail, SMTP credentials, encryption, and sending limits. There is a test sender on this screen.
Payment MethodsWhich methods customers are offered and the credentials for each. See Payment methods.
UsersStaff and customer accounts, and their passwords.
User RolesRoles and per-feature permissions. Each plugin contributes its own permissions, so this list grows with what you have switched on.
TemplatesThe wording of every email the system sends, and the layouts used for invoices and quotes.
ThemeWhich of the included themes to use, and a box for your own CSS. See Customising.
LanguagesTranslating the interface. See below.
CronShows the exact command and the web address for your scheduled task. See Scheduled tasks.
BackupDatabase and file backups, if the zip extension is available.
UpgradeRuns database upgrades after a file update, and checks for new versions.

Currency and tax are per-installation defaults set under System Settings, with per-invoice overrides where that makes sense. If you invoice in more than one currency, add the extra currencies first — they appear as a choice on each invoice afterwards.

Date format is a display preference and changing it does not alter stored data, so it is safe to change at any time.

The interface text runs through a translation layer, so it can be translated without editing any code. Settings → Language lists the strings the application has seen and lets you supply replacements.

Translations you add are stored in the database. You can also drop PHP language files into includes/plugin_language/custom/, which is a separate mechanism from the custom/ override folder described in Customising — do not confuse the two.

Two modes:

  • The server’s own mail. The default. Nothing to configure. Works on many hosts, and on others is silently dropped or goes to spam.
  • SMTP. Tick Use SMTP and give a hostname, username, password and encryption type. Choose TLS for most providers. This is more reliable and much better for deliverability, because the mail is then sent by a server that is allowed to send as your domain.

There is a sending rate limit on the same screen, expressed as a number per minute, hour or day. Set it to match whatever your provider allows, or large newsletter sends will be rejected partway through.

Always use the test sender after changing anything here. If the test arrives and real notifications do not, the problem is the template or the trigger, not the mail settings.