README

Splash Scopes & Field Templates

Define standardized field definitions and feature scopes for Splash connectors.

What is this?

This package provides two complementary layers for Splash connector development:

Field Templates (Splash\Templates) - Standardized field definitions with schema.org microdata, types, and translations.
Feature Scopes (Splash\Scopes) - Groupings of field constraints that define what a connector must provide.

Together, they ensure all connectors expose consistent, well-defined fields for object synchronization.

Installation

composer require splash/scopes

Available Dictionaries

All field templates are organized into interface dictionaries for quick access:

Dictionary	Class	Description
ThirdPartyFields	`Splash\Templates\ThirdPartyFields`	Users, Customers, Companies
AddressFields	`Splash\Templates\AddressFields`	Contact Addresses with Postal Address
ProductFields	`Splash\Templates\ProductFields`	Products / Catalog Items

Field Templates

Field templates are individual PHP classes that define a single field's configuration: type, microdata, labels, and flags.

Each template extends AbstractFieldTemplate and provides:

getName() / getShortDescription() - Translated labels (en/fr)
getMdDescription() - Markdown description for documentation generation (defaults to getShortDescription())
getTechnicalDescription() - Detailed technical description for AI agents and developer tooling (defaults to getShortDescription())
getCoreConfiguration() - Splash field type, microdata (schema.org), flags (required, indexed, etc.)

Template Dictionaries

Templates are organized into interface dictionaries for easy access by connector developers.

use Splash\Templates\ThirdPartyFields;
use Splash\Templates\AddressFields;
use Splash\Templates\Address\PostalAddressFields;

// Use constants to reference field templates
ThirdPartyFields::NAME;          // ThirdParty legal name
ThirdPartyFields::EMAIL;         // ThirdParty email
PostalAddressFields::STREET;     // Street address
PostalAddressFields::CITY;       // City / Locality
AddressFields::PARENT;           // Link to parent ThirdParty

Using Templates from Fields Factory

Use createFromTemplate() to define a field from a template in your Splash object:

use Splash\Templates\ThirdPartyFields;

... 
    /**
     * Build Fields Definition from Templates
     */
    protected function buildTemplatedFields(): void
    {
        $this->fieldsFactory()->createFromTemplate("my-identifier", ThirdPartyFields::PHONE)
            ->isReadOnly()  // Make Templated Field Read-only
        ;
    }
...

The template auto-configures the field type, name, description, microdata, and flags. You can still override any property after applying the template.

Using Templates from Metadata Attributes

With the splash/metadata package, apply a template directly on entity properties:

use Splash\Templates\ThirdPartyFields;

class ThirdParty
{
    #[SPL\Template(ThirdPartyFields::NAME)]
    private ?string $name = null;

    #[SPL\Template(ThirdPartyFields::EMAIL)]
    private ?string $email = null;
}

Creating a New Field Template

Create the template class in the appropriate directory:

namespace Splash\Templates\ThirdParty\Core;

use Splash\Core\Dictionary\Fields\SplFieldProps;
use Splash\Core\Dictionary\SplFields;
use Splash\Core\Models\Fields\AbstractFieldTemplate;

class VatId extends AbstractFieldTemplate
{
    public function getName(?string $isoLang = null): string
    {
        switch ($isoLang) {
            case "fr_FR":
                return "Numero de TVA";
            default:
                return "VAT Number";
        }
    }

    public function getShortDescription(?string $isoLang = null): string
    {
        switch ($isoLang) {
            case "fr_FR":
                return "Numero de TVA intracommunautaire";
            default:
                return "Intra-community VAT Number";
        }
    }

    public function getMdDescription(?string $isoLang = null): string
    {
        return "The VAT identification number of the organization.";
    }

    public function getTechnicalDescription(): string
    {
        return "
            Intra-community VAT identification number.
            Format varies by country (e.g. FR12345678901 for France).
            Used for tax compliance and B2B invoicing.
            This field should be validated against EU VIES database when possible.
        ";
    }

    protected function getCoreConfiguration(string $isoLang): array
    {
        return array(
            SplFieldProps::TYPE           => SplFields::VARCHAR,
            SplFieldProps::MICRODATA_URL  => "http://schema.org/Organization",
            SplFieldProps::MICRODATA_PROP => "vatID",
        );
    }
}

2. Register it in the appropriate dictionary interface:

interface ThirdPartyCoreFields
{
    // ...existing constants...
    const VAT_ID = Core\VatId::class;
}

License

This project is licensed under the MIT License.

splash / scopes

Maintainers

Details