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

Scopes

Scopes are the contracts a connector declares: each one lists the fields a server must expose, in which mode, and the Validator enforces it. Two kinds live in src/scopes/:

Server features (Splash\Scopes\<ObjectType>\<ServerType>, e.g. Order\Oms, SupplierOrder\Erp): highlighted on splashsync.com, declared by connectors, no constraint of their own, they aggregate base scopes.
Base scopes (Splash\Scopes\<Domain>\<Subject><Role>, e.g. Accounting\ItemsReceiver): the building blocks, one contract per subject and direction (Provider, Receiver, Client).

Page	Content
Naming, roles and levels	Class naming, roles, constraint levels, alternatives, search type
Scopes catalog	Every scope with its code, kind, impacted types and embedded scopes, by domain
Templates & scopes catalog	The JSON export of all templates and scopes: bundle, commands, sources, format

// Connector: declare the features the server honours
$this->registerScope(\Splash\Scopes\Order\Oms::class);

// Standalone object service
#[AsStandaloneObject(type: "Order", scopes: array(Order\Shop::class))]

The field constraints of each scope are read from the catalog (php bin/console splash:catalog:build) or from the toolkit MCP server: they are not duplicated in the docs.

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

Package info

Security

Statistics