README

This documentation is also available in these languages:

• Français

This library provides a simple and readable interface to create and manipulate XSD with ease. This library provides many features that aren't available out there in Composer (yet?).

First, this library revolves around Profiles, classes that:

• Fetches any meaningful classes based on library XML-Utils
• Configure any XSD element for perfect rendering: complexType, sequence, choice, restriction
• Allows to build on other Profiles to rename, replace, remove, add specific types you wish to
• Allows to export Profile as a callable action, to use it in a Validator later

Example 1: Rename a type

Suppose you have a specific Type declared as:

class SomeStringType extends Type implements Validator
{
    public function getValidator(): Validator
    {
        return new RegexValidator('xxx');
    }
}

And you wish to achieve this result. Note the name attribute on <simpleType>:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
    <simpleType name="xxx-string">
        <restriction base="NMTOKEN">
            <pattern value="xxx"/>
        </restriction>
    </simpleType>
</schema>

You need to:

1. Create a Finder subclass, to get this SomeStringType type:

class MyFinder extends Finder
{
    public function getResults(): array|NodeCollection
    {
        return [
            new Type(new SomeStringType()),
        ];
    }
}

1. Create a Profile subclass, with builtin transformers, and execute your operation on Finder results:

class MyCustomProfile extends Profile
{
    public function getFinders(): InheritableConfiguration
    {
        // Which class you wish to include in your XSD
        return new InheritableConfiguration(__FUNCTION__, [
            MyFinder::class,
        ]);
    }

    public function getTransformers(): InheritableConfiguration
    {
        // Which transformers you wish to use:
        // - Type: `<simpleType>` tags
        // - Restriction: `<restriction>` tags
        // Other transformers are included in this package
        return (new InheritableConfiguration(__FUNCTION__))
            ->rule(Type::class, [
                'evaluate' => [TypeTransformer::class],
            ])
            ->rule(Restriction::class, [
                'evaluate' => [RegexNmTokenTransformer::class],
            ]);
    }

    public function execute(): void
    {
        if ($this->isExecuted === true) {
            return;
        }
        parent::execute();
        // Rename "some-string" to "xxx-string"
        $this->rename(SomeStringType::class, 'xxx-string');
        
        $this->isExecuted = true;
    }
}

Example 2: Change XSD structure based on another Profile

Suppose you already have a valid Profile, then you need to tweak it for a specific business case.
Your Profile already contains every tag, attribute and restriction you wish to, but for conformance, you want to create a "sub-profile" based on first.

This example suppose you override your Profile with a second one, and only shows the execute() method:

public function execute(): void
{
    if ($this->isExecuted === true) {
        return;
    }

    parent::execute();

    // Targets any tag (Definition)
    $this->target(Definition::class)
        // For a specific tag...
        ->for(
            PersonTag::class,
            fn ($self) => $self
                // Denies attributes based on name
                ->denies('attr-1', 'attr-2')
                // Deny an element based on its TypedAttribute class name
                ->denyElement(FullName::class)
        )
        // For a specific tag...
        ->for(
            Customer::class,
            fn ($self) => $self
                // Deny a single attribute based on name
                ->deny('attr-1')
                // Remove any `attributeGroup`
                ->removeGroups()
                // Merge a group into this Definition
                ->mergeGroup(CustomProperties::class)
        )
        // For these tags
        ->for(
            [
                Company::class,
                Warehouse::class,
            ],
            fn ($self) => $self
                // Allow a specific attribute "attr-x" with validation "StubString"
                ->allow(new TypedAttribute('attr-x', StubString::class))
        );

    $this->isExecuted = true;
}

Features

This library supports:

• Full XSD definition of Choice and Sequence, with minOccurs and maxOccurs
• Attribute Groups with duplicates management
• Attributes with name and type
• Valid rendering of complex validations provided by XML-Utils library
• Fine-tuning of every element: names, references, types, attributes added or removed at runtime...

If you wish to see this library in action, please see Apache FOP profile compared to XSL-FO profile:

• XSL-FO profile
• Apache FOP Profile
• Apache FOP Extension Profile

Why?

First, we could not find an XSD library that provides every aspect we needed:

• davidbadura/xsd-builder provides XSD build, but does not support choice, ability to fine-tune an existing XSD, or complex validations. https://packagist.org/packages/davidbadura/xsd-builder
• typo3/fluid-schema-generator is abandoned and is dedicated to Fluid ViewHelpers.

As XSD isn't exactly fashionable these days, that's understandable. However, we believe strong structure validation of properties and inner elements in an Object-Oriented programming is (and always will be) an important part of validation. This library, built on top on XML-Utils, allows this validation layer.

Finally, for a bit of context, this package is used in XSL-Core package, to ensure conformance on XSL-FO and Apache FOP XSD.

Installation

This library is available on Composer. Install it with:

composer require ls-a/xsd-generator

Changelog

Please refer to the CHANGELOG file to see the latest changes.

Support

We put our heart into delivering high-quality products that are accessible to everyone. If you like our work, don’t hesitate to reach out to us for your next project!

Contributing

Contributions are governed by the CONTRIBUTING file.

Security

If you’ve found a bug or vulnerability, please contact us by email at contact@ls-a.fr instead of opening an issue, in order to protect the security of other users.

Credits

• Renaud Berthier

License

The MIT License (MIT). Please see License File for more information.