This project is not maintained anymore. If you want to take over contact us at tech@cargomedia.ch.
A namespace groups related code. The namespace is used as a prefix for classnames. CM
is a namespace, a classname could be CM_Foo_BarZoo
.
One application can serve multiple sites (extending CM_Site_Abstract
).
Each HTTP-request (CM_Http_Request_Abstract
) is matched against the available sites (::match()
), before it is processed.
A site contains multiple Namespaces (for models and controllers) and themes (for views).
A view (extending CM_View_Abstract
) can be rendered, usually as HTML. The following view types are pre-defined:
CM_Layout_Abstract
: HTML-document.CM_Page_Abstract
: A page of the web application. Is actually a component itself.CM_Component_Abstract
: Sub-part of an HTML-document.CM_Form_Abstract
: Form with input elements and actions.CM_FormField_Abstract
: Form input field.CM_Mail_Mailable
: E-mail.A model (extending CM_Model_Abstract
) represents a "real-world" object, reads and writes data from a key-value store and provides functionality on top of that.
Every model is identified by an id, with which in can be instantiated:
$foo = new Foo(123);
By default, the constructor expects an integer value for the ID. Internally, it is stored as a key-value store (array), which can be exposed if there's need for a more complex model identification.
To validate and enforce type casting of your models' fields, define an appropriate schema definition:
protected function _getSchema() {
return new CM_Model_Schema_Definition(array(
'fieldA' => array('type' => 'int'),
'fieldB' => array('type' => 'string', 'optional' => true),
'fieldC' => array('type' => 'CM_Model_Example'),
));
}
Fields with a model's class name as a type will be converted forth and back between an object and a json representation of its ID when reading and writing from the data store.
If present, the persistence storage adapter will be used to load and save a model's data.
public static function getPersistenceClass() {
return 'CM_Model_StorageAdapter_Database';
}
In this example, the database adapter's load()
and save()
methods will be called whenever you instantiate an existing model or update schema fields.
The CM_Model_StorageAdapter_Database
will make use of following naming conventions to persist models in a database:
You can access a model's fields with _get()
and _set()
, which will consider the schema for type coercion.
It is recommended to implement a pair of getter and setter for each field in order to keep field names internal:
/**
* @return string|null
*/
public function getFieldB() {
return $this->_get('fieldB');
}
/**
* @param string|null $fieldB
*/
public function setFieldB($fieldB) {
$this->_set('fieldB', $fieldB);
}
/**
* @return CM_Model_Example
*/
public function getFieldC() {
return $this->_get('fieldC');
}
/**
* @param CM_Model_Example $fieldC
*/
public function setFieldC($fieldC) {
$this->_set('fieldC', $fieldC);
}
By default, the data is cached between multiple reads in Memcache. Use getCacheClass()
to change this behaviour:
public static function getCacheClass() {
return 'CM_Model_StorageAdapter_CacheLocal';
}
Alternatively if you're not using a persistence storage adapter, you can implement a custom method _loadData()
which should return an array of the model's key-value data.
In this case, your setters are responsible for persistence and should still call _set()
for caching.
Models with a persistence storage adapter can be created by using their setters followed by a commit()
:
$foo = new Foo();
$foo->setFieldA(23);
$foo->setFieldB('bar');
$foo->commit();
For deleting models, just call:
$foo = new Foo(123);
$foo->delete();
Alternatively, if you're not using a persistence storage adapter, you can implement your own creation logic in _createStatic(array $data)
and then create models with:
$foo = Foo::createStatic(array('fieldA' => 1, 'fieldB' => 'hello world'));
In this case, make sure to delete the corresponding records within _onDelete()
(see below).
The following methods will be called for different events in the lifetime of a model:
_onCreate()
: After persistence, when a model was created._onChange()
: After persistence, when a field's value was changed. Also after the model was created._onDelete()
: Before persistence, when a model is deleted.A paging is an ordered collection with pagination-capabilities.
The data source for a paging is a PagingSource (CM_PagingSource_Sql
, CM_PagingSource_Elasticsearch
etc.).
Caching can be enabled optionally with enableCache()
.
Items within a paging can be post-processed before being returned. For example one can instantiate an object for the id returned from the database.
Naming convention:
CM_Paging_<Type of item>_<Lookup description>
CM_Paging_Photo_User # All photos of a given user
CM_Paging_User_Country # All users from a given country
Class definitions should be grouped by topic and stored in a common directory. Within such a topic module directories should be used to group files with common parent classes. A topic module can again contain a directory for another (sub) topic module.
Example of a topic module "Payments", inside another topic module "Accounting":
library/
└── CM
└── Payments
├── Accounting
│ ├── Account.php
│ ├── Transaction.php
│ └── TransactionList
│ ├── Abstract.php
│ └── User.php
├── Bank.php
├── BankList
│ ├── Abstract.php
│ ├── All.php
│ └── PaymentProvider.php
├── ExchangeRateUpdater.php
└── SetupScript.php
Views like components and pages need to reside in their respective directory. It's recommended to group them by topic within a sub-directory.
Example of components for the topic "Payments":
library/
└── CM
└── Component
└── Payments
├── AccountList.js
├── AccountList.php
├── TransactionList.js
└── TransactionList.php
In your workspace, run:
composer create-project cargomedia/cm-project --stability=dev <project-name>
This will create a new directory <project-name>
containing a project based on CM.
CM framework provides a base which should be extended. Our own libraries should be part of different namespace. To create one simply run:
bin/cm generator create-namespace <namespace>
To simplify creation of common framework modules, but also to help understanding of its structure there is a generator tool. It helps with scaffolding framework views and simple classes. It also allows easy addition of new namespace or site.
generator create-view <class-name>
Creates new view based on the
generator create-class <class-name>
Creates new
CM framework comes with its own set of command line tools to easily run common php routines.
To see full list of available commands simply execute bin/cm
.
Usage:
[options] <command> [arguments]
Options:
--quiet
--quiet-warnings
--non-interactive
--forks=<value>
Commands:
app fill-caches
app generate-config-internal
app set-config <filename> <config-json> [--merge]
app setup [--reload]
cache clear
console interactive
db db-to-file <namespace>
db file-to-db
frontend generate-favicon
frontend icon-refresh
generator create-class <class-name>
generator create-module <module-name> [--single-module-structure] [--module-path=<value>]
generator create-view <class-name>
job-distribution start-worker
location outdated [--verbose]
location upgrade [--without-ip-blocks] [--verbose]
maintenance start
media-streams import-archive <stream-channel-media-id> <archive-source>
media-streams import-video-thumbnail <stream-channel-media-id> <thumbnail-source> <create-stamp>
message-stream start-synchronization
migration add [--namespace=<value>] [--name=<value>]
migration run [--name=<value>]
search-index create [--index-name=<value>] [--skip-if-exist]
search-index delete [--index-name=<value>]
search-index optimize
search-index update [--index-name=<value>]
Apart from setting whole infrastructure (http server, various services) application itself needs some preparation.
Each CM application heavily depends on types which are integer identifiers for classes. In order to keep fixed identifier (class name can change) we require to store those in VCS-stored config file (internal.php). In order to generate types run:
$ bin/cm app generate-config-internal
This will generate resources/config/internal.php
and resources/config/js/internal.js
files required for application to work. Keep this file in VCS at it needs to be preserved between releases.
Most CM applications require services to be setup and/or some initial data inserted. To do so CM Framework uses so-called provision scripts.
There is built-in command for running all setup-scripts defined in $config->CM_App->setupScriptClasses
config property.
$ bin/cm app setup
Provision scripts are responsible for setting up everything app-related - from creating database schema to loading fixtures.
All those scripts need to be classes extending CM_Provision_Script_Abstract
and therefore implement load
and shouldBeLoaded
method.
Anytime scripts are about to be loaded they will be first checked if they actually should, by running shouldBeLoaded
.
Once this is positive it will run load
.
Additionally provision scripts can implement CM_Provision_Script_UnloadableInterface
with corresponding unload
and shouldBeUnloaded
methods.
Migration scripts are located in [modulePath]/resources/migration
directories, they are executed in module
registration order (see extra.cm-modules
in composer.json
), then by script filename natural order.
CM_Migration_UpgradableInterface
interfaceCM_Service_ManagerAwareInterface
to gain access to the service managerUpgradableInterface::up
PHP documentation block will be displayed during the script execution if availablecm migration run
cm migration run --name=<filename>
ie:
bin/cm migration run
- 1485180420_Foo…
- 1485180453_Bar: some description coming from PHP doc…
cm migration add
[root]/resources/migration
and with the current git branch namecm migration add --namespace=<module-name> --name=<script-name>
ie:
bin/cm migration add --namespace=Foo --name=Bar
`/home/vagrant/cm/library/Foo/resources/migration/1485180453_Bar.php` generated