Developing With Symfony
From OrangeHRM
This document describes how the Symfony Framework should be used with OrangeHRM. The Symfony configuration details are given for information only and a configured version of the code with one UI page (PIM employee list) converted to use Symfony will be available.
Contents |
Symfony
Symfony version 1.2 should be used and will be included inside the orangehrm source tree. This document does not cover usage of the symfony framework in detail and the Symfony documentation should be referred for more details.
Symfony plugins
Doctrine with the sfDoctrinePlugin is used as the For ORM layer. This plugin is available but not enabled in the default Symfony installation. Currently Symfony uses Propel ORM by default, but they will be moving to Doctrine from Symfony 1.3. See this blog posting for reasons behind this move.
For unit testing, PHPUnit is used via the sfPhpunitPlugin.
Directory organization
To avoid cluttering the root OrangeHRM directory, symfony framework related files/directories are located under the symfony directory in OrangeHRM source. This is temporary, and when more OrangeHRM modules are moved over to use Symfony, we can consider moving these files/directories to the root folder.
The directory structure under the symfony directory is the default for Symfony, and you would get a similar structure if you follow the Symfony documentation.
Plugins are enabled in the config/ProjectConfiguration.class.php file in Symfony
Symfony Project organization
A Symfony project can have multiple applications, with each application having multiple modules. In addition, the project can use multiple plugins.
OrangeHRM Application
OrangeHRM uses a single application named orangehrm. (symfony/apps/orangehrm)
Symfony Modules
Symfony modules should be logical units in the application. These do not necessarily have to map to OrangeHRM modules like admin, leave etc. For instance, Job titles could be one module and job specification can be another module. This keeps the action classes and the urls simple. eg: /jobtitle/list to list job titles.
Therefore one OrangeHRM module (eg: admin) can have multiple Symfony modules (jobtitle, skills, users etc.) This is the only organization currently required, however, we will be considering grouping a number of symfony modules to make this clearer. This will be done by organizing them into Symfony plugins or in some other way.
A module can be created using the following command:
php symfony generate:module orangehrm moduleName
Configuration
The symfony related code is not yet integrated into the OrangeHRM installer. Therefore, they have to be configured separately. At a minimum, the file config/databases.yml has to be edited with the correct database connection details.
Database access
Doctrine is used as the ORM layer. Read the symfony and Doctrine documentation for more information. The database schema is defined in config/doctrine/schema.yml. This an edited extract from a schema autogenerated using symfony commands. Therefore, this should not be overwritten, only edited to add more tables.
Currently only a few existing OrangeHRM tables are included in schema.yml. Existing tables can be added to this by either manually entering into schema.yml or backing up the schema.yml file and running
php symfony doctrine:build-schema
This will generate a schema file for all the existing tables in OrangeHRM database. The schema for the required tables only can then be copied to the original schema.yml and edited to suit naming conventions.
Creating database tables
The doctrine schema is not used to generate database tables. Therefore, the SQL necessary to create these tables have to be added to the dbscript.sql, dbscript-1.sql and dbscript-2.sql under the dbscript directory at the top level of the OrangeHRM source.
Table names should follow the existing table names.
Model classes
Model classes can be generated from the schema file. This generates the the abstract Base model classes under lib/model/doctrine/base and a blank subclass under lib/model/doctrine. The base class should not be modified. See Symfony documentation for more information.
Integration with existing OrangeHRM code
Most of the OrangeHRM code is not using symfony. It may be necessary to access existing code from new modules being developed using Symfony.
Configuration
OrangeHRM's main configuration files are Conf.php, sysConf.php and mailConf.php located under the lib/confs directory. Of these sysConf.php and Conf.php are currently accessible via the OrangeConfig class.
$maxEmployees = OrangeConfig::getInstance()->getSysConf()->maxEmployees;
The ROOT_PATH and WPATH definitions used in OrangeHRM are available to symfony code as well. They are defined in the front controller files (web/index.php and web/orangehrm_dev.php)
Unifying the session
The Symfony configuration was changed to use the default PHP session name (PHPSESSID) to make it easier to access session variables set by existing OrangeHRM code. This may present problem when installing if php.ini has a none default session name. That will be handled later when integrating the new code with the installer.
Session variables set in existing OrangeHRM code can be access directly through the $_SESSION variable.
User Authentication and Authorization
Authentication
Authentication and authorization is currently performed by existing non-symfony code. The myUser class in the OrangeHRM application was modified to check for the session variable created at login. The login module and action is set to auth/login in apps/orangehrm/config/settings.yml. If the user is not authenticated, he is directed to the login action which redirects him to the OrangeHRM login page. This is only an intermediate solution.
In summary, authentication is already set up and will just work for new symfony modules. If a particular page needs to be accessible without login, that can be changed by adding a security.yml to the particular module. eg:
jobs: is_secure: off
Authorization
Symfony code can use the existing authorization mechanism in OrangeHRM. This is work-in-progress, but is usable.
Actions can be protected by configuring credentials in security.yml for the module. For example, the following allows Admin, Supervisor or Manager roles to access the index action and only the Admin role access to the delete action. The assign action is only allowed for a user with both Supervisor and Manager role. Any other actions in this module is accessible by any logged in user.
index: credentials: [[Admin, Supervisor, Manager]] delete: credentials: [Admin] assign: credentials: [Supervisor, Manager]
OrangeHRM also has the concept of admin user groups and permissions per module. Details on accessing these will be updated later.
Existing Classes
In some cases, new modules written using Symfony will need to access existing OrangeHRM classes. This can be done by one of the following methods.
Directly include the required php files
The required PHP files can be directly included using, for example, require_once.
One issue with this is that there is a possibility of naming conflicts between new symfony based classes and existing classes. This will only be a temporary issue, until the older code is moved to the symfony framework. In this case it is recommended that some of the other options are tried, and if not sufficient, the new class is renamed to avoid the naming conflict.
Existing models
If it's only required to get details of models linked to a new model class being developed, the related model classes can be added to the schema file and the autogenerated classes can be used from the new code.
Internationalization
OrangeHRM supports language files. These are available under the language directory at the top level. How to use these language files in symfony code has not yet been decided. This section will be updated with more details when that is available.
Forms
Forms is view object in a symfony.More about Symfony Forms
Unit Testing
sfPhpunitPlugin is used for unit testing. See the Readme page of the plugin for details on using it. This section will be updated with more details.
