PHP DSL Elements: Making Library APIs Easier to Use

When developing our internal framework (unfortunately, PHP generally contributes to the constant reinvention of the bicycle), we tried to design library module interfaces in such a way that the client code using these interfaces would be simple, concise and readable.

Ideally, a specialized module designed to solve a particular problem should form a simplified language that allows the developer to describe the solution or result of solving the problem as close as possible to the terms of the subject area. If at the same time we do not go beyond the framework of the programming language used, we are talking about implementing the so-called internal DSL .



A lot has been written about the implementation of DSL in various languages, for example, is available on the Fowler websitecatalog of patterns on this topic . The features of any design pattern are largely determined by the implementation language; this is doubly true for DSL patterns. Unfortunately, the range of possibilities that PHP can provide is extremely limited. Nevertheless, using two standard templates - Method Chaining and Expression Builder , you can achieve a more convenient and readable API.

Proper naming of classes and methods is half the battle when developing a DSL-style API. It is important that the methods are named as close as possible to the subject area, and not to the software implementation. It sounds corny, but you can find a lot of examples when naming is due, for example, to the implementation of one or another classic design pattern from GoF .

The use of method chains makes the code more concise and in some cases allows achieving the effect of a specialized DSL. When developing library modules, we try to follow the rule: if the method does not return a functionally necessary result, let it return $this. We also usually provide a set of methods for setting the internal properties of an object, which allows you to configure object parameters inside an expression and also makes the code more concise.

The Builder pattern allows you to more conveniently build systems of nested objects when the parent contains links to children, those, in turn, to their children and so on. Note that in PHP it is advisable to avoid bidirectional links (the parent object refers to the child, and the child refers to the parent), since the garbage collector does not work with circular links.

To create such systems, we will create a very simple base class:

2. class DSL_Builder {
3.  
4.   protected $parent;
5.   protected $object;
6.  
7.   public function __construct($parent, $object) {
8.     $this->parent = $parent;
9.     $this->object = $object;
10.   }
11.  
12.   public function __get($property) {
13.     switch ($property) {
14.       case 'end':
15.         return $this->parent ? $this->parent : $this->object;
16.       case 'object':
17.         return $this->$property;
18.       default:
19.         throw new Core_MissingPropertyException($property);
20.     }
21.   }
22.  
23.   public function __set($property, $value) { throw new Core_ReadOnlyObjectException($this); }
24.  
25.   public function __isset($property) {
26.     switch ($property) {
27.       case 'object':
28.         return isset($this->$property);
29.       default:
30.         return false;
31.     }
32.   }
33.  
34.   public function __unset($property) { throw new Core_ReadOnlyObjectException($this); }
35.  
36.   public function __call($method, $args) {
37.     method_exists($this->object, $method) ?
38.       call_user_func_array(array($this->object, $method), $args) :
39.       $this->object->$method = $args[ 0];
40.     return $this;
41.   }
42. }
43. ?>

Objects of this class configure the target object, a reference to which is stored in the field $object, delegating to it a call to methods and setting properties. Of course, the builder object can also define a set of its own methods for more complex configuration of the target object. In this case, the pseudo- endproperty allows you to return to the builder of the parent object, and so on.

Based on this class, we write the simplest DSL to describe the configuration of the application.

2. class Config_DSL_Builder extends DSL_Builder {
3.  
4.   public function __construct(Config_DSL_Builder $parent = null, stdClass $object = null) {
5.     parent::__construct($parent, Core::if_null($object, new stdClass()));
6.   }
7.  
8.   public function load($file) {
9.     ob_start();
10.     include($file);
11.     ob_end_clean();
12.     return $this;
13.   }
14.  
15.   public function begin($name) {
16.     return new Config_DSL_Builder($this, $this->object->$name = new stdClass());
17.   }
18.  
19.   public function __get($property) {
20.     return (strpos($property, 'begin_') ===  0) ?
21.       $this->begin(substr($property, 6)) :
22.       parent::__get($property);
23.   }
24.  
25.   public function __call($method, $args) {
26.     $this->object->$method = $args[ 0];
27.     return $this;
28.   }
29. }
30. ?>

Now we can create a file config.phpin which to describe the configuration of our application in this form:

2. $this->
3.   begin_db->
4.     dsn('mysql://user:password@localhost/db')->
5.   end->
6.   begin_cache->
7.     dsn('dummy://')->
8.     default_timeout(300)->
9.     timeouts(array(
10.       'front/index' => 300,
11.       'news/most_popular' => 300,
12.       'news/category' => 300))->
13.   end->
14.   begin_site->
15.     begin_from->
16.       top_limit(7)->
17.     end->
18.     begin_news->
19.       most_popular_limit(5)->
20.     end->
21.  end;
22. ?>

You can load the configuration using the call:

2. $config = Config_DSL::Builder()->load('config.php');
3. ?>

Of course, the matter is not limited only to configs. For example, we describe the structure of a REST application like this:

2. WS_REST_DSL::Application()->
3.       media_type('html', 'text/html', true)->
4.       media_type('rss', 'application/xhtml+xml')->
5.       begin_resource('gallery', 'App.Photo.Gallery', 'galleries/{id:\d+}')->
6.         for_format('html')->
7.           get_for('{page_no:\d+}', 'index')->
8.           post_for('vote', 'vote')->
9.           index()->
10.         end->
11.       end->
12.       begin_resource('index', 'App.Photo.Index')->
13.         for_format('rss')->
14.          get('index_rss')->
15.          get_for('top', 'top_rss')->
16.         end->
17.         for_format('html')->
18.           get_for('{page_no:\d+}', 'index')->
19.           index()->
20.         end->
21.       end->
22.  
23.   end;
24. ?>

Using fast DSL-style APIs allows you to get short and well-readable code, for example, in application controller methods:

2. public function index($page_no = 1) {
3.     $pager = Data_Pagination::pager($this->db->photo->galleries->count(), $page_no, self::PAGE_LIMIT);
4.  
5.     return $this->html('index')->
6.       with(array(
7.         'top' => $this->db->photo->galleries->most_important()->select(),
8.         'pager' => $pager,
9.         'galleries' => $this->db->photo->galleries->
10.                                published()->
11.                                paginate_with($pager)->
12.                                select()));
13.   }
14. ?>

In some relatively rare cases, you can go even further. By expanding the class a little DSL_Builder, you can describe not only a static structure, but also a set of actions, that is, a certain scenario. For example, you can work with the Google AdWords API like this:

2. Service_Google_AdWords_DSL::Script()->
3.   for_campaign($campaign_id)->
4.     for_ad_group($group_id)->
5.       for_each('text', 'keyword1', 'keyword2', 'keyword3')->
6.         add_keyword_criteria()->
7.           bind('text')->
8.         end->
9.       end->
10.       add_ad()->
11.         with('headline', 'headline',
12.              'displayUrl', 'www.techart.ru',
13.              'destinationUrl', 'http://www.techart.ru/',
14.              'description1', 'desc1',
15.              'description2', 'desc2')->
16.         format("Ad Created")->
17.       end->
18.     end->
19.   end->
20.   for_each_campaign()->
21.     format("Campaign: %d, %s\n", 'campaign.id', 'campaign.name')->
22.     dump('campaign')->
23.     for_each_ad_group()->
24.       format("Ad group: %d, %s\n", 'ad_group.id', 'ad_group.name')->
25.       for_each_criteria()->
26.         format("Criteria: %d, %s\n", 'criteria.id', 'criteria.text')->
27.       end->
28.     end->
29.   end->
30. end->
31.   run_for(Service_Google_AdWords::Client()->
32.             useragent('user agent')->
33.             email('email@domain.com'));
34. ?>

Of course, this approach should be used within reasonable limits, but sometimes it gives a very good result.