Simplify puli.json

[webmozart]

Right now, we mostly recommend to use the Puli CLI for configuring Puli packages. Unfortunately, using CLI programs is a problem for many developers. Therefore I propose to simplify the puli.json schema in order to make it more accessible to a larger crowd of developers.

Thanks to our JSON migrations (#96), we can do this without breaking any existing projects.

One step in this direction is described in #167.

Furthermore, I think we should rename "path-mappings" (back) to "resources", which seems easier to understand:

{
    "resources": {
        "/app": "res",
        "/twig/twig/views/exceptions": "res/views/exceptions"
    },
    "override": ["twig/twig"]
}

In addition, a "resources-dev" key should be added for resources that are only loaded in the development environment.

The entry "bindings" should be renamed to "provide" and restructured as follows:

{
    "provide": {
        "My\\Demo\\DemoBundle": "Symfony\\Component\\Kernel\\BundleInterface",
        "My\\Demo\\MoneyType": "Doctrine\\Dbal\\Type",
        "/app/trans/*.xlf": "php-fig/xliff-translations"
    }
}

Equally, "provide-dev" should be added for development-only bindings.

When an artifact should be bound to multiple types, we can use an array:

{
    "provide": {
        "/app/trans/*.xlf": [
            "php-fig/xliff-translations",
            "some-translator/xliff-translations",
        ]
    }
}

If a binding type has parameters, we can change the simple type string to an object:

{
    "provide": {
        "/app/trans/*.xlf": {
            "type": "php-fig/xliff-translations",
            "parameters": { "domain": "messages" }
        }
    }
}

This will have a few consequences:

• It will not be possible anymore to disable bindings, since we don't store UUIDs anymore by default. I don't think this feature is highly needed.

• Each binding type will only accept one kind of artifact (e.g. class or resource or ...) that is defined with the binding type:

  {
      "binding-types": {
          "php-fig/xliff-translations": "resource",
          "Symfony\\Component\\Kernel\\BundleInterface": "class"
      }
  }

  Depending on the artifact accepted by a binding type, we can construct the right binding class (ResourceBinding, ClassBinding, ...) for the LHS of "provide". New artifacts types can be added by providing implementations of a new BindingFactory interface (replaces Add BindingSerializer interface #171) or similar:

  class ServiceBindingFactory implements BindingFactory
  {
      public function getName()
      {
          return 'my-service';
      }
  
      public function createBindingType($name, array $parameters)
      {
          // possibility e.g. to validate $name
          return new BindingType($name, ServiceBinding::class, $parameters);
      }
  
      public function createBinding($artifact, $typeName, array $parameterValues)
      {
          // $artifact could be the service name in the container
          return new ServiceBinding($artifact, $typeName, $parameterValues);
      }
  }

  {
      "provide": {
          "My\\ServiceBindingFactory": "Puli\\Discovery\\Api\\BindingFactory,
      }
  }

  Disclaimer: I don't think adding ServiceBindings is the best example, since containers usually offer better approaches to solve this problem. I can'think of any better though right now.

Opinions?

[tgalopin]

Furthermore, I think we should rename "path-mappings" (back) to "resources", which seems easier to
understand.

I agree 100%.

In addition, a "resources-dev" key should be added for resources that are only loaded in
the development environment.

What is the use-case of this?

The entry "bindings" should be renamed to "provide" and restructured

That's a good idea. What about using the same name in the CLI?

Globally, I think it's a great idea. Most people tend to edit JSON files by hand and don't use CLI, we should try to simply their job :) .

[mnapoli]

This is awesome, all of this! I like using the CLI but as you said, many users would rather edit the file themselves.

It will not be possible anymore to disable bindings, since we don't store UUIDs anymore by default. I don't think this feature is highly needed.

Is it (will it be) possible to disable completely a module?

Why I ask this: in some frameworks (e.g. Symfony) you register bundles/modules explicitly with code which leads to a 2 step install:

• install the package using Composer
• enable the package in your app/framework

I started playing with a simpler process based on Puli: install the package, and that's it. However I need to offer a way to users to disable a module (without uninstalling it). I may be going a wrong path (explicitly enabling a package is probably better) but I'd like to know if Puli can offer that.

[webmozart]

@mnapoli We can easily add a way to disable packages, e.g. (similarly to "override"):

{
    "disable": [
        "vendor/package",
    ]
}

[webmozart]

We could also rename "override-order" to "reorder". This option can already be used to tell Puli to load a package "a" before a package "b":

{
    "reorder": [
        "vendor/a",
        "vendor/b",
    ]
}

Note that you don't need to include the names of any other installed packages (e.g. "c", "d" and "e") in this list if you don't want to.

One possible caveat: At the moment, packages that are loaded later override packages that are loaded earlier. So if "a" and "b" contain a resource mapped to the same Puli path, the one from "b" will be preferred. Is this expected?

[mnapoli]

if "a" and "b" contain a resource mapped to the same Puli path, the one from "b" will be preferred. Is this expected?

To me it makes sense. What would happen to packages not defined in "order": do they get appended to the list or prepended?

[webmozart]

@mnapoli That's undefined. The only guarantee we make is that packages are loadedin an order that respects all the "override" keys and the "reorder" key in the root package.

[temp]

Like it! 👍
Making things easier is always appreciated.
We are having a lot of bindings, but never had the necessity to enable/disable single bindings.

[webmozart]

This is WIP in puli/manager#56