Merge pull request #4 from symfony-cmf/added_basic_docs

Added some basic documentation

Author: wouterj

CoreBundle/SlugifierInterface.php

@@ -5,7 +5,8 @@
 /**
  * @deprecated Since 1.0, to be removed in 2.0. Use Symfony\Cmf\Api\Slugifier\SlugifierInterface instead.
  */
-interface SlugifierInterface {
+interface SlugifierInterface 
+{
     /**
      * Return a slugified (or urlized) representation of a given string.
      *

README.md

@@ -7,27 +7,72 @@
 This package is part of the [Symfony Content Management Framework (CMF)](http://cmf.symfony.com/)
 and licensed under the [MIT License](LICENSE).
 
-The Slugifier API provides a basic interface to use for third party slugifiers.
-Besides this, it comes with a usefull `CallbackSlugifier` which is capable of
-handling most third party slugifiers.
+A "slugifier" is a function which transforms a string `such as this` into a
+URL-friendly string `such-as-this`. Slugifiers are also known as "urlizers".
 
+This package does not contain a slugifier implementation, it provides a
+standard interface (`SlugifierInterface`) for use by third party slugifiers
+and a `CallbackSlugifier` which is capable of wrapping most non-implementing
+third-party slugifiers to the `SlugifierInterface`.
 
 ## Requirements
 
 * See also the `require` section of [composer.json](composer.json)
 
-
 ## Documentation
 
-For the install guide and reference, see:
+Perhaps the best way to document this simple component is with a
+demonstration. You have an event subscriber which slugifies the title of a
+blog post:
+
+```php
+<?php
+
+use Symfony\Cmf\Api\Slugifier\SlugifierInterface;
+
+class FooSubscriber
+{
+    private $slugifier;
+
+    public function __construct(SlugifierInterface $slugifier)
+    {
+        $this->slugifier = $slugifier;
+    }
 
-* Slugifier documentation
+    public function onEntitySave(\Some\Event $event)
+    {
+         $entity = $event->getEntity();
+         $entity->setSlug($this->slugifier->slugify($entity->getTitle());
+    }
+}
+```
+
+You can then inject either a slugifier which already implements the CMF
+``SlugifierInterface`` or you can use non-implementing libraries using the
+`CallbackSlugifier`. The
+[RoutingAutoBundle](https://github.com/symfony-cmf/RoutingAutoBundle) uses
+[aferrandini/urlizer](https://github.com/aferrandini/Urlizer) package:
+
+```php
+$slugifier = new CallbackSlugifier('Ferrandini\Urlizer::urlize');
+$fooSubscriber = new FooSubscriber($slugifier);
+```
+
+By using the Slugifier package you decouple your application from the slugifier
+implementation.
 
 See also:
 
 * [All Symfony CMF documentation](http://symfony.com/doc/master/cmf/index.html) - complete Symfony CMF reference
 * [Symfony CMF Website](http://cmf.symfony.com/) - introduction, live demo, support and community links
 
+## FIG Proposal
+
+We [proposed this to
+FIG](https://groups.google.com/forum/?fromgroups=#!topic/php-fig/J-6s9Wlyk-A)
+but unfortunately the proposal did not get enough interest. We would still be
+happy to contribute this to a PSR should the interest come up and deprecate
+this package in favor of the PSR one.
 
 ## Contributing