Monday, August 20, 2012

Announcing the CyclonePHP project

In this blog post I'm announcing the CyclonePHP project for the PHP developer community.

In short, CyclonePHP is (will be) an application development framework for PHP 5.3 consisting of some loosely coupled libraries. The aim of the project is to provide a reliable RAD solution for web developers willing to create medium-sized business applications with fairly long maintenance interval. CyclonePHP is developed with keeping in mind both reliable functionality and small resource cost (performance overhead caused by the framework) in mind. The main goal is to keep the code simple, meaning that simple things should be easy to implement for the framework users, but making it flexible and extensible enough to develop complex functionalities too. The core of the framework consists of a small core library containing a lightweight router and request dispatcher built on the HMVC design pattern in addition to a good set of helper (utility) classes. The core library of the framework is based on Kohana 3.0.7.

What does CyclonePHP offer?

The most notable component of the framework is its ORM (Object-Relational Mapping) library called JORK. JORK provides an expressive but easy-to-learn object query language (available as an internal DSL) and an extensive active record implementation for run-time model handling. Since the heart of most web applications is a relational database - of course it is often used together with a NoSQL solution but only in some rare cases is NoSQL on its own a good choice for modeling complex data schema - it is a crucial factor when putting together the technology stack of a web application to pick a reliable ORM library for RDBMS management. Since most of a web application is about data management it must be easy to work with data, processing data and binding data to user interface. JORK is going to be a reliable solution for such needs. While it keeps simple operations really simple and putting as small mapping overhead as possible it still makes complex querying and data maninulation possible, easy to implement and performance effective at the same time.

Other important libraries of CyclonePHP are CyForm and the DB module. CyForm is a form management library for handling common HTML form lifecycle with simplistic databinding support. It offers an expressive way to define the model of HTML forms and a simple API for managing forms from application controllers. The DB library is a database abstraction layer which makes it possible to create and execute database queries and DML statements in a DBMS-independent way to improve application portability. It is a wrapper component which - unlike many similar libraries - supports a wide variety of the capabilities of common databases like transactions, prepared statements, sophisticated error handling, SQL injection protection and most importantly transient wrapping of different SQL dialects. The library also offers a very small active record implementation which does not handle connections between entities but still can be a good choice for small applications which don't need a complex ORM system (note: the active record of the DB library is totally independent from JORK). The query builder API of the DB library also acts as a lower level backend of JORK.

Past and future

I started to work on CyclonePHP almost 2 years ago. A long time passed, I have spent really lot of time on it and many important features and libraries have been developed, but the system is far not production-ready. I made the framework publicly available in this blogpost because most of the things are fairly well documented, in its current state of the framework it is possible for interested people to look at the libraries, try them out and play with them. The documentation is not much but will be enough to try out the stuff.

On the other hand a lot of work still has to be done. All of the existing components should be improved. Not only coding but some other development-related things should be done, for example versioning policy and release scheduling. This is a bit obscure now, since the currently released 0.9 (developer preview) version of the whole framework includes all libraries which are not versioned separately, but later on I want to distribute the framework libraries as standalone libraries too which can be used separately. My goal is to make it possible to use the libraries as drop-ins to projects built on other frameworks, keeping a PSR-0 compliant autoloader as the only requirement. I'm on the right way from this point of view but the exact distribution and installation process must be defined. I would also like to make it possible to install the CyclonePHP libraries via the composer package management tool as an alternative method of standalone installation. The release scheduling is a bit different topic. In this current release - and probably in the next few ones too - I just want to get feedback, I would like to see the reactions of the PHP community. In the next few months API breaks and major changes are merely possible. If it seems to me it makes sense to continue the project then during the spring of 2013 the first stable version of the framework will be released and an exact versioning policy and release schedule will be defined. One things is sure: if the framework will be successful then all of the "official" libraries will be supported for at least 4 years this way ensuring the long-time reliability.

Why yet another framework?

I'm sure many experienced PHP developers asked the question while reading this announcement: why yet another PHP framework? We all know that there are so many existing solutions with very similar functionalities for solving absolutely the same problems met by PHP developers during their everyday work.

Well, I haven't started developing CyclonePHP "just because" or "just for fun", I had some good reasons to do so. I have tried out - well, probably not all, but numerous existing PHP frameworks as an application developer. If I would like to give a detailed answer to the above question then it would consist of a long list of what I've tried out and describe why I have decided not to use them, but probably it would be both boring and an unethical trolling toward other frameworks, therefore I don't give a detailed answer here. The short answer is that I have found some of the frameworks slow and - although they provided good features - I stood against paying an extremely high performance cost for implementing both trivial and complex functionalities too. I have found an other group of frameworks fast, small, easy to learn, develop with, but after some time I felt them immature, architecturally under-abstracted and in some cases I met some constraints set by frameworks which simply didn't enable me to do what I want. In the latter group I've found Kohana which I happily used for some projects and it served as a root of the CyclonePHP project.

Kohana and CyclonePHP - saying sorry

As it is fairly well known in the Kohana community, Kohana is a small, extensible framework to build your own framework on the top of it. Almost every Kohana users customize it by adding their own modules and/or modifying the core itself. Initially I did the same, implemented some small modules which I needed for my small projects as a beginner/intermediate developer. Later on some things changed, I started writing more complex libraries which were dependent on each other or reimplemented some core features or an official Kohana module. I didn't share my job since my libraries didn't have proper, detailed documentation so it wouldn't made sense, although I planned to share my libs as a set of Kohana modules designed to operate together. As the time passed more and more things changed in my framework, more and more core components of Kohana has been replaced or rewritten - it seemed to be more and more hard to distribute it as a set of Kohana extensions, but over several months I tried to do my best to keep API compatibility with Kohana to avoid the "yet another framework" effect. During the development the scope of the project also changed: I wanted to put together a framework which is more enterprise-ready, more reliable, more robust and much more featureful as Kohana. From the reliability point of view I have faced a serious problem: the Kohana utility classes pollute the global namespace, they don't take the advantage of the PHP 5.3 namespaces (to keep PHP 5.2 compatility). What's worse, they don't even have a common classname prefix. It can cause hardly predictable and even harder solvable problems for application developers. If someone wants to use a third-party PHP library or wants to interoperate with legacy PHP code which also uses the global namespace then classname collisions can easily happen (practically if a library uses a class which has the same name as a utility class in Kohana - well, not much to do). Such collisions rarely rarely occur but the more an application is complex the higher is the chance of such case. I wanted to avoid such problems therefore I made a major refactoring on the core framework and on all of my libraries: I started using namespaces and moved every class under the cyclone namepsace and its subnamespaces. It was a really hard decision since at this point I totally broke API compatibility with Kohana, but I hope it was the right way to go the ensure the reliability of CyclonePHP. Furthermore some parts of the codebase became more readable since before the namespace refactoring I have used Really_Very_Long_Class_Names at some places. On the other hand I'm absolutely not happy about breaking backwards-compatibility with Kohana and I would like to say sorry to the Kohana core team - although don't exclude the possibility of making some of the CyclonePHP libraries available as "unnamespaced" Kohana modules on demand.


After describing the most important features of CyclonePHP, its current state of development and its relation to Kohana let's see some features not mentioned yet:
  • The configuration handler of Kohana is replaced by a new one which makes environment-specific settings available
  • The logger from the Kohana core is removed and is replaced by a separate logger library
  • The CyclonePHP core library defines a simple CLI API which can be used by library developers to define commands executable from the CLI by application developers - it can be useful both for implementing scheduled cronjobs or provide command-line development tools belonging to libraries
  • The routing process is improved and the request dispatcher has been re-implemented. Although CyclonePHP was started from Kohana 3.0.7 many ideas - and code - have been taken from the Kohana 3.1 request dispatcher.
  • The View handling is totally refactored to make the integration of third-party template libraries easier, but it needs further improvements.
  • CyclonePHP comes with an API documentation generator written from scratch. Unlike the Kohana useguide module it generates offline HTML documentation therefore no running Kohana instance is needed to read the docs. I have evaluated some other API documentation generator tools too, mainly Doxygen and PHPDocumentor, but both lacked some features which were required for the needs of the CyclonePHP project. Since it also has some problems it might be removed from later versions - we will see.
  • There are some tasks often faced by developers which are not solved yet by any CyclonePHP libraries. At least a pagination library will be implemented until the first stable release of the framework, and a cache library is also needed but probably it will be only a simple port of the Kohana cache module. Other recommendations are welcome.
  • On Github you can find a repository named CyTpl. It is an experimental template library - it will almost surely be excluded from the stable release.

Joining the community

You can read more about the project or join the community using the following channels:
  • the official website of the project is (under development)
  • The user manual and API documentation is available online at
  • some developer documentation can be read on the github wiki
  • is the community forum
  • you may follow @cyclonephp on twitter
  • the IRC channel of the project is #cyclonephp on FreeNode
  • if you have ideas related to the project what you don't want to share at the community forum then you can contact me at "crystal at".


Although most of the CyclonePHP libraries are implemented by me or were taken from Kohana, there were some contributors from the University of Debrecen (Hungary) who helped my job by implementing some features or fixing some bugs:
  • Zoltán Tóth (CLI API initial implementation)
  • Lajos Pajger (table name prefix implementation in the DB library)
  • Dániel Tóth (AssetPool improvements)
  • Zsolt Háló (persistent connections for the MySQL adapter of the DB library)
  • Lóránt Perjéssy (misc.)

No comments:

Post a Comment