[5.x] Add support for collection entry blueprints loaded via addons

[xenco]

This PR enables addons to supply predefined blueprints for existing collections.

Closes statamic/ideas#1327.

Problem
Statamic previously introduced addon blueprint loading support (see #9324), but it was limited to top-level blueprints only. It did not allow addons to add blueprints to existing collections—for example, adding an extra blueprint to the "pages" collection to support features like a page builder with addon-provided and autoloaded fieldsets.

Solution
This PR extends the blueprint loading mechanism, enabling addons to load entry blueprints for any existing collection. To make use of this functionality, addons must follow this directory structure:

Addon Root
└── resources/
    └── blueprints/
        └── collections/
            └── {collection-handle}/
                └── {blueprint-name}.yaml

Which will result in the addon blueprints being visible and selectable for that collections entries.

[duncanmcclean]

It looks like this has caused a bunch of test failures. Would you be able to take a look?

Most of them are the same error:

[xenco]

I think the errors are caused by where I initially placed the changes. Although the modifications were only relevant for collections, they unintentionally affected all blueprints.
Additionally, the tests aren't configured yet to handle the new method addonEntryBlueprints in the Blueprint Facade.
I've now moved the logic directly into the collection and the tests run fine locally.

Sorry if this caused confusion or still is not the right way of doing things. It's my first time working with the core.
I hope my explanation makes sense and this change can be integrated into the codebase.

[duncanmcclean]

No worries!

[edalzell]

How is this different than the addon use the blueprint found event?

[xenco]

Hi @edalzell, if existing functionality already covers my use case, could you please provide me with an example?

Just registering the blueprints to a namespace does not work for me. I tried multiple variations of namespace and path. Still only the top-level blueprints are registered.

public function bootAddon()
{
    Blueprint::addNamespace("collections.pages", base_path('resources/blueprints/collections/pages'));
}

[benatoff]

Hi, while I like this change very much since I have the same problem as well it leads to inconsistent behavior.
Example: The package myPackage wants to add a customPages Blueprint to the Pages Collection. If this Blueprint is changed and saved in the cp Statamic will create a New Blueprint in resources/blueprints/collections/pages/my_package_custom_pages.yaml.

This changed blueprint will NOT be used and will be overwritten by the plugins blueprint.

I would argue that similar to similar to Laravel Standard and how Fieldsets are handled the customized Blueprint should land in resources/blueprints/vendors/myPackage/collections/pages/custompage.yaml and override plugins blueprint.

[duncanmcclean]

If existing functionality already covers my use case, could you please provide me with an example?

Addons can currently listen to the EntryBlueprintFound event, which allows them to ensure/append fields before the blueprint is rendered in the CP.

For example:

<?php

namespace App\Listeners;

use Statamic\Events\EntryBlueprintFound;

class AddExtraFields
{
    /**
     * Create the event listener.
     */
    public function __construct()
    {
        //
    }

    /**
     * Handle the event.
     */
    public function handle(EntryBlueprintFound $event): void
    {
        $event->blueprint->ensureField('example_field', [
            'type' => 'text',
            'display' => 'Example field',
        ]);
    }
}

Addons can also register publishables, allowing users to copy files (like blueprint YAML files) using Laravel's vendor:publish command.

The Blueprint::addNamespace() method is intended for addons who wish to make their own blueprints, separate from collection blueprints.

[jasonvarga]

Thanks for the PR and sorry for the delay. Your addon could publish a blueprint yaml file to resources/vendor/collections/{collection}/{blueprint}.yaml.