[Proposal] A recipe for Symfony Flex

[covex-nn]

The main blocker for recipe is a db_driver parameter - it is required and it's possible values cannot be used without installing additional packages.

We could make that parameter optional with no_driver default value, like i suggested in FriendsOfSymfony/FOSUserBundle#2708. The main goal of a default value is to pass cache:clear stage without errors and to make a recipe valid.

With a new driver some services like sonata.media.manager.media must be created, because other services depend on them. I suggest to create a new classes for that services, that will throw exceptions on usage in runtime with instructions for a developer what to do next.

With a default db_driver we will have a recipe with default configuration for MediaBundle. This configuration will be extended by recipes for specific meta package, i.e. sonata-project/media-orm-pack or sonata-project/media-phpcr-pack. All such packages will require sonata-project/media-bundle and conflict with each other. Each pack recipe will contain only Entity, Document or PHPCR classes with annotations, that will be copied into src directory during installation. So, no new maker or easy-extends bundle will be required.

[kunicmarko20]

Can't we add configuration with db_driver: orm to the pack and then copy it from the pack?

[covex-nn]

MediaBundle does not require doctrine/doctrine-bundle, so db_driver: doctrine_orm will cause an error:

The service "sonata.media.serializer.handler.gallery" has a dependency on a non-existent service "doctrine"

[kunicmarko20]

Well, that part we could leave to dev? and we just give them a choice of 3 packs? cc @sonata-project/contributors does that sound valid?

[covex-nn]

A recipe for sonata-project/media-orm-pack will contain db_driver: doctrine_orm! Also sonata-project/media-orm-pack will require sonata-project/media-bundle, doctrine/doctrine-bundle and doctrine/orm. So, after sonata-project/media-orm-pack installation, MediaBundle will be fully functional

[kunicmarko20]

So a pack can require additional libs? Then that is it, we just create packs and we are done?

[jordisala1991]

IMO it is a great idea to just use packs

[covex-nn]

MediaBundle recipe could have it's default configuration:

sonata_media:
    default_context: default
    contexts:
        default:
            providers:
                - sonata.media.provider.youtube
                - sonata.media.provider.image
                - sonata.media.provider.file
                - sonata.media.provider.vimeo
            formats:
                small: { width: 100 , quality: 70}
                big:   { width: 500 , quality: 70}

    cdn:
        server:
            path: /upload/media

    filesystem:
        local:
            directory: "%kernel.project_dir%/public/upload/media"
            create: false

And then pack recipe will have only storage configuration (and Entity/Document/PHPCR classes):

sonata_media:
    class:
        media: App\Entity\SonataMediaMedia
        gallery: App\Entity\SonataMediaGallery
        gallery_has_media: App\Entity\SonataMediaGalleryHasMedia
    db_driver: doctrine_orm

[kunicmarko20]

That sounds good, but then if someone installs media without a pack, he would still get an error?

[covex-nn]

Right now, if someone installs MediaBundle 3.x-dev with Flex, there will be a error in console after composer require sonata-project/media-bundle 3.x-dev:

Executing script cache:clear [KO]
[KO]
Script cache:clear returned with error code 1
!!
!! In ArrayNode.php line 230:
!!
!! The child node "db_driver" at path "sonata_media" must be configured.
!!
!!
!!

If my proposal will be accepted, developer will see similar error in dev environment on a web-page. Exception will be decorated by symfony/debug-bundle and will contain instructions for developer. So, error will be anyway, because MediaBundle must be configured properly.

[kunicmarko20]

basically, if they install it in any way (without a pack) they would get an error? Ok, your proposal is great, I think we can move forward like this for all bundles and deprecate easy-extends

[covex-nn]

Without a pack error will be in runtime, and there won't be errors after installation during cache:clear, so a recipe will be valid and will be accepted

[jordisala1991]

We can't deprecate easy-extends for now, because it contains a class used in this (and other bundles), but we can get close to it.

[kunicmarko20]

You mean we can't remove it? We can deprecate it?

[jordisala1991]

SonataMediaBundle/src/DependencyInjection/SonataMediaExtension.php

Line 15 in 73e80e1

use Sonata\EasyExtendsBundle\Mapper\DoctrineCollector;

[kunicmarko20]

But when we add recipe:

SonataMediaBundle/src/DependencyInjection/SonataMediaExtension.php

Line 273 in 73e80e1

public function registerDoctrineMapping(array $config)

That won't be called anymore, so we can deprecate easy extends and on Media 4.x remove that part?

[kunicmarko20]

Oh, no, that would be called because of classes 🤔

[kunicmarko20]

We would need to find a different way or move that part somewhere else?

[covex-nn]

Pack recipe will contain all classes for entities, and there will be all doctrine mappings. See gist. But, i have classes only for doctrine orm =(

[kunicmarko20]

We still allow them to change that class in configuration, so this won't work, it has to be done through Extension.

[covex-nn]

@kunicmarko20 i found, that EasyExtendsBundle cannot be optional for MediaBundle right now. It is required, because EasyExtends is not just a file-generator-from-template - it checks and fixes doctrine mappings in Sonata\EasyExtendsBundle\Mapper\DoctrineORMMapper::loadClassMetadata

But if entity will be described correctly via annotations, it will not update anything, i.e. see here. So, it is not a blocker for my proposal: EasyExtends will be used for non-flex applications as file-generator and doctrine-mappings-fixer; for flex applications it will not be used any more

[kunicmarko20]

hm, you are right, with annotations we do not need that part at all (Sonata\EasyExtendsBundle\Mapper\DoctrineORMMapper::loadClassMetadata). But still, we could deprecate easy extends and remove it in 4.x?

[covex-nn]

The purpose of EasyExtends is to create correct Entities/Documents/PHPCRs to project. With Flex this goal will be reached via copying files from recipe. For developers, who do not want to use Flex we could create a documentation like here (see tabs for PHP / XML), that will contain code of Entity/Document/PHPCR in PHP/XML/Yaml format. Also we can say "just copy files from recipe manualy" and give a link to symfony/recipe-contrib =)

So, yes, i think EasyExtends could be deprecated. Right now (1) Doctrine Mapper code could be copied somewhere to Core (or to some new doctrine-extensions-bundle), (2) EasyExtends mapper could use that new core mapper (for BC), (3) bundles, that use EasyExtends as a Doctrine Mapper could be switched from EasyExtends to Core. But deprecation should be done only after we will have all recipes for all bundles and all documentation about manual Entity/Document/PHPCR creation without Flex.

[kunicmarko20]

But we do not need that doctrine mapper anymore? If I am correct it was used to add associations but we will already have them with your copy/pasting from flex recipe?

[covex-nn]

We will need doctrine mapper only for those project, that were already installed using documentation before future changes, because entities must be fixed by EasyExtends. So, it cannot be deprecated in current version, because there is no alternative. I think, we can remove dependency on sonata-project/easy-extends-bundle only in current master to avoid BC break, and only after we will get a recipe for Flex. To deprecate EasyExtends in current version we must move doctine mapper somewhere.

Btw, i wonder why doctrine entity associations are not added (and should be fixed) in GalleryHasMedia.orm.xml.skeleton, and a similar reference is added in GalleryHasMedia.phpcr.xml.skeleton?

[kunicmarko20]

If I am correct, they are not added because classes can be changed in the config by you. If we don't deprecate the mapper now, can we remove it in 4.x 🤔 cc @sonata-project/contributors

[jordisala1991]

I dont know, but IMO thats a discussion for later, the recipe can be created without deprecating anything. And when we see how it works, we can deprecate it if we need to

[kunicmarko20]

True, if I am correct, we need to create repos for packs, right @covex-nn ?

[covex-nn]

@kunicmarko20 yes, and that repos should contain only composer.json file with sonata-project/media-bundle dependency and all other "recomended" dependencies. A type of a package shoud be symfony-pack like in symfony/orm-pack. Repo for Doctrine ORM also could require: doctrine/doctrine-bundle and doctrine/orm or just sonata-project/doctrine-orm-admin-bundle (i like it even more!). Package name could be like sonata-project/media-orm-pack =)

[kunicmarko20]

As you are involved and had this great idea about packs, can you create a list of all the packs we need and make an issue on dev-kit? We need @rande to create repos and it would be good if we have the list of all we need.

[jordisala1991]

Yes, but how do we create the entities on the pack?

[covex-nn]

@jordisala1991 entity classes will be stored with recipe in symfony/recipes-contrib, they will be copied into src/Entity directory during pack installation. I prepared a gist with entity classes (i use them in my current project), these classes could be used as prototype for recipe

[kunicmarko20]

but that means we would need all types of entities in recipe, we can't save them in the pack?

[jordisala1991]

To summarize:

We create a recipe for media-bundle with the basic configuration
We create a repository for the orm pack containing the composer.json with the needed requirements
We create another recipe for the pack containing the entities for the orm

Is that right?

[covex-nn]

@kunicmarko20 actualy, we can do this: we could use copy-from-package Flex configurator feature. But, i think, that having that files in symfony/recipes-contrinb and giving control on that files to the community is a better way. And i am not sure, that pack can have files besides composer.json (i have not seen such examples)

@jordisala1991 yes, that's right. Also there will be 2 another recipes with PHPCR and Document classes, when somebody will create such files

[kunicmarko20]

so we would have 3 recipes per bundle? can that even be done?

[covex-nn]

MediaBundle supports Entity, Document and PHPCR
ClassificationBundle, UserBundle, NewsBundle, and CommentBundle - Entity and Document
Also there are 6 bundles that support only Entity

I have Entity classes with annotations for NotificationBundle and PageBundle. UserBundle cannot have a recipe until FOSUserBundle does not have it. So, after MediaBundle it won't be difficult to create Documents for 3 other bundles and Entities for all others.

[kunicmarko20]

We just confirmed on slack (#symfony-flex) that every pack can have its own recipe, so basically, we can have 3 packs for media bundle and one would have entities other one documents etc. The end user would just require pack they need and flex will do the rest

[kunicmarko20]

I just rechecked you only forgot the TimelineBundle. So we would need 1+ packs for that 7 bundles.

[covex-nn]

There are 11 bundles in my list:

• Page, Article, ClassificationMedia, Timeline and Dashboard supports only Entity. I guess, these bundles can have only one recipe
• Notification can work with and without Entity - 2 recipes
• Classification, User, News, and Comment supports Entity and Document - 3 recipes
• Media supports Entity, Document and PHPCR - 4 recipes

Did i miss something?

[kunicmarko20]

Ah, Article and Comment are missing docs page, that is why I did not see them. So we need to create recipe + pack per persistence mechanism?

[covex-nn]

Article supports only Entity, so there is no need in a pack. We can create a recipe for sonata-project/article-bundle

[kunicmarko20]

My bad, so the ones that support only 1 type can have just a recipe, everything else needs recipe + packs