How to Create a Third-Party Symfony Bundle

Have an awesome library you want to integrate in your Symfony application? Share your code between different Symfony instances? Share your code with other people? Create your bundle standalone and distribute it via Composer! Here is a short overview on how to do it.

To get started, you want to have a Composer & a git instance (if you follow the general practice to publish your bundle on a git-based central repository, such as GitHub or GitLab) running. All a Symfony third-party bundle has to be is a composer package. Everything else is bonus. To make your project a composer package, you add the `composer.json` file if you did not already. In it, you specify the name, properties and dependencies of your bundle. Comparsion with other bundles helps to get an impression of what to put in there.
Basically, it could look like mine for my PlaceholderBundle:

{
    "name" : "bernhard-webstudio/placeholder-bundle",
    "type" : "symfony-bundle",
    "description" : "Symfony bundle to generate placeholders for images",
    "keywords" : ["Symfony", "Placeholder"],
    "homepage" : "https://github.com/BernhardWebstudio/PlaceholderBundle",
    "license" : "MIT",
    "authors" :
    [
        {
            "name" : "Tim Bernhard",
            "email" : "tim@bernhard-webstudio.ch",
            "homepage" : "http://genieblog.ch",
            "role" : "Developer"
        }
    ],

After adding the boni, you will want to publish your bundle so other people can benefit from your bundle. There are various tutorials for this already so I will not write on.

Boni

To give the Symfony character to your package, you will want to integrate e.g. dependency injection, expose a class as a service or use the general Symfony configuration for your services. This can easily be achieved by adding the relevant Symfony components as dependencies via composer, e.g. use command composer require symfony/dependency-injection. Afterwards, you can use them the same way you are using them in your Symfony application. Pay attention not to limit the dependency versions too much, otherwise you may prevent a user from upgrading Symfony.

There are may boni you can add to your repository, if it is published on e.g. GitHub: to give users and contributors a chance to better understand the state of your repository, integrate some of the apps and add badges to your README file.

Finally, let’s talk testing: as your package should not ship with a Kernel oder similar, you have nothing to simply run. There are workarounds: either you let your bundle live in a complete application, e.g. as a submodule, and test the application as a whole. Or you use unit-testing. If your choice falls on the latter, I can recommend using ConfigTest if your bundle uses the configuration component. Also, at one point, you may have to have an AppKernel to test the execution of a command or the availability of a route. Depending on the actual need, you can either mock the Kernel or create a TestKernel. For latter are many examples online in other bundles, e.g. in mine.

Loading Likes...

My first third-party Symfony Bundle

I created my first open-source Symfony bundle: PlaceholderBundle. It is an abstraction of Primitive /a> and/or SQIP for use in a PHP respectively Symfony application. This way, you can automatically generate nice & adaptive placeholders for images in the format you like, all in your PHP application or your Twig template. Refer to the documentation on how to use the PlaceholderBundle. For now, the underlying nodejs packages still have to be installed separately, depending on which you want to use. The configuration allows to personalise the placeholders as much as the underlying applications allow it.

I will write a follow-up on how to begin with developing a third-pary bundle, as I think the resources for it are rather limited. A general tip is to checkout existing bundles on how to do it.

Loading Likes...

How to Encode an SVG for the `src`-Attribute using PHP

As SVGs should preferably not be base64 encoded when setting them on an -tag src-attribute, the suggested alternative is to URL-encode them. The standard PHP urlencode function unfortunately is not suitable for this task, as the resulting value is not interpreted by any browser as a valid SVG image. Instead, the function rawurlencode has to be used. Took me some time to realize. As soon as you get this, you can also take over some other optimizations; maybe get inspired by Taylor Hunts mini-svg-uri to decode some characters manually to improve the overall size. A final function could possibly look like this:

function svgUrlEncode($svgPath)
{
$data = \file_get_contents($svgPath);
$data = \preg_replace('/\v(?:[\v\h]+)/', ' ', $data);
$data = \str_replace('"', "'", $data);
$data = \rawurlencode($data);
// re-decode a few characters understood by browsers to improve compression
$data = \str_replace('%20', ' ', $data);
$data = \str_replace('%3D', '=', $data);
$data = \str_replace('%3A', ':', $data);
$data = \str_replace('%2F', '/', $data);
return $data;
}

Loading Likes...

Getting started with elastica queries in Symfony

When integrating Elasticsearch with Symfony, there can be a few troubles for newcomers.

The easiest way to achieve integration is by following the setup instructions of the FOSElasticaBundle, in case you have a running Elasticsearch instance already at least. Symfony 3.1 or higher is required for this bundle. When following the setup instructions, there are a few caveats, which differed from what I expected. In the following post, I try to sketch some of the problems respectively solutions.

  • FOSElasticaBundle will not automatically recognize properties of an objectf, even when the serializer and the persistence model is defined. The properties you want to be mapped have to be listed in the configuration file.
  • To map relations such as ManyToOne, ManyToMany or OneToOne, the property gets a subkey “type” with value “nested”, after which the a new “properties” key is necessary followed by the properties of the related Entity
  • To create a development environment separat from the production index, simply set the index_name attribute of the relevant index to a environment-dependent value, such as “app_%kernel.environment%”

When you finally have the configuration set up, you have to run ./bin/console-dev fos:elastica:populate. This will show you errors in the configuration, if you have some, respectively sync your database with the elasticsearch instance.
The next step you will want to take is to use Elasticsearch to search, duh. This can get tricky at first if you are used to SQL search queries, especially as the relevant query classes are not yet as good documented as expected. The best way for me was to combine the knowledge of which classes exist with the elasticsearch documentation itself.

To translate from an SQL query to an Elastica-Query, keep the following in mind:

  • should means OR
  • must means AND
  • mustNot means XOR
  • to wrap these conditions together, use the Elastica\Query\BoolQuery
  • joins can be simulated with the Elastica\Query\Nested
  • to make comparsions with dates or numbers, use Elastica\Query\Range

With this knowledge, a query such as (...) WHERE (post.title LIKE %$search% OR creator.firstName LIKE %$search% OR creator.lastName LIKE %$search%) AND post.start < $date translates to (for example, in a custom search repository class, extends FOS\ElasticaBundle\Repository) :

setQuery($search)->setFields('firstName', 'lastName');
                $creatorQuery->setPath('creator')->setQuery($nameQuery);
          $textQuery->addShould($creatorQuery);
                $titleQuery = new Match('title', $search);
          $textQuery->addShould($titleQuery);
$overallQuery->addMust($textQuery);
          $dateQuery = new Range('start', array('lt' => $date->format(ELASTICA_DATE_FORMAT)));
$overallQuery->addMust($dateQuery);

/** ... **/

This query can be executed like it is on the finder/repository yielding results. But. It will not work with a Paginator and a default number of 10 results will be returned instead. To successfully get the PaginatorAdabter, the whole BoolQuery has to be wrapped in an Elastica\Query Object.
This could be achieved e.g.:

$query = new Query();
// code from above
$query->setQuery($overallQuery);

And to get the Pagination working:

$elasticaFinder->createPaginatorAdapter($query);

Loading Likes...

Setting the default value of a Symfony FormType nested in CollectionType

There are a few proposed ways to hack a default value to form fields. The problen gets bigger when handling CollectionTypes, as the underlying objects don’t get constructed automatically. Workarounds are numerous, e.g. simply setting prototype_data on the CollectionType to an instantiated object. Unfortunately, for me, not one of these worked out when working with nested CollectionTypes.

The only way that worked out for me was adding a DataTransformer which checks in the reverseTransform function whether the object to transform is null, and if, set it to a new instance instead. The default values are than set in the constructor of the underlying object or in the reverseTransform function too, depending on your (performance) needs.

I sure hope this gets improved one day, but for now, this workaround is very comprehensible so I would not think about submitting an issue or pull request or even ask why this is necessary. This way, I even have more control over the new objects.

Loading Likes...