Last Bites
Share your views and comments with the developers of Scorpio in the forums, bug tracker or email.
Scorpio Framework for PHP
© Copyright 2007-2012 Dave Redfern
Posted by Dave Redfern (Writer), Documentation on 13 Apr 2008 @ 11:43
Scorpio like most frameworks uses a set of configuration files to hold various parameters so that they might be updated more easily. All the config files are XML based and very simple. They understand "sections" and "params" and can be marked to be overridden or not.
Config files are read by the systemConfig system. This is used for the system level config and is extended for the mvcSiteConfig. MVC config parameters can be used to override the global parameters IF this is permitted in the global config file.
The main configuration file is located in the /libraries folder and is named: config.xml. This is the system level configuration file that should contain your global settings, e.g. database connection details, default log level and log type etc.
The following table lists the most common sections and parameters that can be placed in this file.
| Section | Parameter | Description | Default |
|---|---|---|---|
| app | Holds application parameters that are used in the generators and as copyright information in the MVC system | ||
| author | The application author | ||
| copyright | Copyright information e.g. My Company @ My Domain (c) YEAR | ||
| version | The application version | ||
| database | Main database configuration options> | ||
| dsn |
Data Source Name, the connection string to use when connecting to the DB | %TYPE%://%USER%:%PASSWORD%@%HOST%/%DATABASE% | |
| user(Web|Script|Daemon) |
Scorpio DB users; each is used to identify where a query is running from (web, CLI or daemon process). If PHP is running in CGI mode, then all Web scripts appear as a CLI script. | scorpio | |
| userPassword |
The password for the user accounts (should set the same for all users) | ||
| system |
Main system database name | scorpio_system | |
| logging |
Main logging database name (only needed if using DB logging) | scorpio_logging | |
| wurfl |
Main WURFL database name | scorpio_wurfl | |
| MyDbName |
A generic name for your database (e.g. mydb => user_mysitedb) | ||
| type |
Database type, must be a supported PDO database type | mysql | |
| host |
Database server address | localhost | |
| port |
Database connection port | 3306 | |
| default |
The default database to connect to if none is specified | system | |
| datetime |
The format of the date time field | Y-m-d H:i:s | |
| date |
The format of a date | Y-m-d | |
| time |
The format of the time | H:i:s | |
| paths | Location of various system folders | ||
| base | Automatically set on startup to the location of system.inc | ||
| classes | Third party classes folder / folder for your generated classes | ||
| libraries | The main library folder | ||
| apps | Applications folder for CLI apps (not tools) | ||
| data | User data folder | ||
| daemons | Daemon processes (POSIX systems only) | ||
| logs | Main log location where log files will be written to | ||
| temp | Temporary files | ||
| tools | CLI tools | ||
| deprecated | |||
| websites | Public websites folder (also known as public_html or htdocs) | ||
| templateTemp |
Root template caching folder usually located in "temp", used by templateCompile and templateCache as the parent folder unless they are specified elsewhere. | ||
| templateCompile |
Template engine compile folder (if required) | ||
| templateCache |
Template engine cache folder (if required) | ||
| system | System level settings | ||
| isProduction | Places the system into a production state and attempts to suppress most error messages. | true | |
| registerErrorHandler | Default true, registers the Scorpio framework error handler as the system error handler. | true | |
| registerExceptionHandler | Default true, registers the Scorpio framework exception handler (which maps exceptions to the error handler) as the system exception handler. | true | |
| registerDefaultDatabaseDsn | Whether or not to register the DSN string as the default DB DSN | true | |
| checkFolderPermissions | Should the temp and log folder permissions be checked on every execution | true | |
| fromAddress | Default system email address e.g. webmaster@mydomain.com | ||
| hostname | The default server hostname e.g. www.mydomain.com | ||
| group | The group name to run daemons under (POSIX only) | ||
| groupGid | The POSIX group ID of group (calculated directly from group) | ||
| user | The user to run daemons under (POSIX only) | ||
| userId | The POSIX user ID of user (calculated directly from user) | ||
| uriSeparator | The default separator character for URI strings | _ | |
| logType | A valid systemLogWriter type class name | systemLogWriterFile | |
| logFolderPermissions | When folders are created by logging system, they are assigned this set of permissions | 0755 | |
| logFilePermissions | Same as above but for the files | 0644 | |
| logLevel | Any valid systemLogLevel integer | WARNING (8) | |
| logDateFormat | The date format that is prefixed to each line of a log message | d/m/Y H:i:s | |
| timezone | The timezone that should be set for the system e.g. Europe/London, UTC, America/Toronto etc. | UTC | |
| locale | The default system locale (since v.0.1.4) | en | |
| wurfl | Various WURFL system settings | ||
| uriLocation | The full web URI to the master WURFL.xml file from the WURFL project | http://wurfl.sourceforge.net/wurfl.xml | |
| maxImportSize | The maximum allowed file size in bytes for importing via the web interface. Importing data is intensive, so this should be kept low. | 512000 | |
| maxExportSize | The maximum number of devices that can be exported in one go via the web interface | 100 | |
| images | Image generation settings> | ||
| maxImageSizeForPreview | The maximum allowed file size for images that previews will be generated for in bytes | 512000 | |
| previewWidth | Preview width in pixels | 40 | |
| previewHeight | Preview height in pixels | 40 | |
| generator | Code generator settings | ||
| daoTemplate | The name of the default DAO template to be used when building data objects. Custom files should be stored in /data/templates/generator | default.tpl | |
| testCaseTemplate | The name of the default test case template used to build test cases in the generator. Custom files should be stored in /data/templates/generator | testCase.tpl | |
| userTemplates | The location of the user templates folder for storing custom generator templates | %DATA%/templates/generator | |
| mvcGenerator | MVC Code generator settings | ||
| userTemplates | The location of the user templates folder for storing custom generator templates | %DATA%/templates/mvcGenerator |
The MVC system has additional configuration parameters over the system level settings. While most system settings could be placed within a site config, it is discouraged.
The MVC site config is in the exact same format as the main system config with sections and params and has full support of overridable components. There are a couple of differences though:
The main MVC settings are listed in the table below.
| Section | Param | Description |
|---|---|---|
| site | The main site configuration | |
| parent |
The parent site folder name |
|
| active |
Is this site active |
|
| uriTextSeparator |
The URI text character separator (- or _) |
|
| theme |
The theme in use by this site, located in /base/themes |
|
| templateEngine |
The template engine in use by the site if not the default Smarty engine. This must be a valid engine listed in mvcViewEngineFactory |
|
| controllerMapFilename |
The name of the controllerMap file default: controllerMap.xml |
|
| controllerMap |
The full path to the controller map file (automatically generated) |
|
| defaultController |
If no request is made, this is the default controller to route the request too e.g. home |
|
| path |
The path to this site (automatically generated) |
|
| alwaysPreloadSiteClasses* | Enable or disable pre-loading of custom classes during the distributor start-up (default true) | |
| autoloadCacheEnabled* | Enable the caching of controller class and library data, may improve performance (default true) | |
| autoloadCacheAutoSave* | Enable or disable the registering of a shutdown handler that will automatically commit changes to the autoload cache back to the file system (default true) | |
| cacheStaticPages | Should static pages be cached (default true) | |
| logLevel | Site specific logLevel, should be on the valid logLevels from systemLogLevel. (default 8 - warning) | |
| useCaptchaOnLoginForms | If true, will use a captcha on admin login forms or on sites that are configured to support this option. (default true) | |
| plugins |
Plugins options |
|
| libraryPath |
The path to the plugins library files, used within the mvcAutoload system |
|
| classes |
Additional classes that should be loaded at engine start up, each parameter is a class name with the parameter being the name of the file containing that class. These classes should be located within the libraries folder of the site. |
|
| className |
Example entry. className.class.php |
|
| mvcController |
The main site specific mvcController class |
|
| mvcSession |
The site specific session class |
|
| mvcView |
The site specific view class |
|
| mvcViewGeneric |
A generic view class not inheriting from mvcViewBase |
|
| These options are used with the admin system to make it easier to build admin controllers for Data Access objects. |
||
| mvcDaoController |
Data Access Object Controller class, used in the baseAdminSite for handling requests to DAO objects |
|
| mvcDaoModel |
Data Access Object Model class; contains logic for the handling of DAO classes in a model context |
|
| mvcDaoView |
Data Access Object View class; contains the logic for generating the various views for DAO objects | |
| i18n | Internationalisation options | |
| active | Is the internationalisation layer active on the site (default false, 0) | |
| identifier | The markup identifier used for declaring text to be translated. For Smarty this is the tag (default t), for PHP templates, this is the function or method name. | |
| defaultLanguage | The default language specified as a valid systemLocale e.g. en, eng_GB, en_US de_DE etc. | |
| adaptor | The name of the translateAdaptor engine to use for reading translation files. This should be the trailing name e.g. array, ini, tmx, qt. (default array) | |
| adaptorOptions | A string of pipe (|) separated options for the adaptor e.g. param=value|Param2=value2 (default disableNotices=true|scan=directory) | |
| distributorPlugins | Enable or disable distributor plugins. Plugins are enabled as needed, but can be disabled on a per site basis | |
| mvcDistributorPluginLog | Enable site specific logs, 0 (zero) to disable. | |
| mvcDistributorPluginSession | Enable session support for a site, 0 (zero) to disable | |
| mvcDistributorPluginDetectDevice | Enables mobile device detection and output mapping | |
| mvcDistributorPluginLocale | Enables locale support via session, get, request etc. | |
| captcha | Settings for the captcha controller | |
| width | Width of captcha image in pixels | |
| height | Height of captcha image in pixels | |
| length | The length of the captcha string (default 6 characters) | |
| login | Settings for the admin system login restriction system | |
| maxDailyLoginAttempts | The number of failed logins before an account is locked for the day |
*Warning: it is possible to break a site by mis-using these options. If you set to NOT pre-load classes in and then use custom libraries during initialisation your site will fail - possibly silently. Only disable it if you either do not make use of custom libraries (e.g. mvcSession, mvcController etc) or if you have an MVC autoload cache already set with these entries.
mvcAutoload cache files can be generated via the scorpio.php CLI tool.
The MVC system uses a controller map to specify which controllers are available to the site. This is unique to each site and must always be created. It cannot be inherited from other sites.
The controller map differs from the other config files listed so far by being more like the site map. It features only a few tags, namely: controllers and controller. A controller can contain a controllers group and the file itself is contained in a controllers tag pair.
The contents of this file will directly mirror what will be available to the site. It can be auto-generated using the admin site if the various controllers exist within the controllers database.
A very basic controller map may look like the following:
<controllers>
<controller name="home" description="Home Page" />
<controller name="static" description="A Static Page" />
</controllers>
This config allows for a single controller called "home" and is the default configuration of the base controllerMap.xml file. Each controller "name" relates to a class prefix within the controllers folder of the site. The controller can exist in any site within the site hierarchy.
An example is the static page controller. This controller can be found in:
/websites/base/controllers/static
However it can be accessed by any site just by including:
< controller name="static" / >
In the site controllerMap file. The MVC system will look down through the parent site config options until it reaches the base site (all sites should ultimately resolve to the base site).
A controller can take the following parameters as attributes on the controller tag:
| Attribute | Description |
|---|---|
| name | The controller class prefix, usually relates to a nameContorller .class.php file |
| description |
A friendly text description for the controller, if not set, the controller name is split apart and each word is capitalised e.g. siteEditor -> Site Editor |
| path |
The full path to the file containing the controller if it is not within the controller map path e.g. a controller userAdmin is located in controlPanel/userManager/ by default the system will look for /controlPanel/userManager/userAdminController.class.php within the controllers folder. If it is not located here, the path must be e.g.: set /users/userAdminController.class.php |
Share your views and comments with the developers of Scorpio in the forums, bug tracker or email.
Scorpio Framework for PHP
© Copyright 2007-2012 Dave Redfern