Custom Services

Pattern management

These services are focused around discovery of libraries and patterns. Additionally, some of these services provide solutions for working with discovered patterns in various ways.

Library Namespace Resolver (patternkit.library.namespace_resolver)

A service to map pattern library namespaces to the Drupal extension libraries providing them. This service consumes the discovered library information from Drupal core, and extends it with additional data and processing for any library definitions defining a patterns key and associated plugin data to drive discovery.

When working with library data before the individual patterns have been discovered, this is the central service for that process.

Pattern Discovery (patternkit.pattern.discovery)

A service for discovery and loading of raw pattern definitions as returned directly from plugin discovery on pattern library definitions. This service enables loading of the discovered pattern definitions which is an important piece of instantiating the Pattern entities based on them.

Pattern Discovery Collector (patternkit.pattern.discovery.collector)

An internal service responsible for much of the legwork for the Pattern Discovery service. This service handles requests from the Pattern Discovery service and attempts to load pattern definitions from cached data, and handles any cache misses by running the pattern library parser plugins on the related library definitions as needed to discover the requested pattern definitions.

Pattern Dependency Resolver (patternkit.pattern.dependency_resolver)

A service to identify dependencies in patterns and load them in the most efficient order.

Getting All Pattern Dependencies

When working with complex patterns composed of many, sometimes multilevel, references, the patternkit.pattern.dependency_resolver service may be used to recursively identify all schema dependencies from a pattern. Using the getOrderedDependencies() method, it will also recommend the sequence for loading them from least to most dependencies in order to ensure patterns are loaded efficiently.

$dependencies = \Drupal::service('patternkit.pattern.dependency_resolver')
  ->getOrderedDependencies('@my/super/pattern');

Pattern Repository (patternkit.pattern.repository)

A service for loading pattern entities from their definitions and creating bundled schemas containing all referenced dependencies.

New Way to Instantiate Patterns

Previously, the most direct path to loading a pattern and getting the schema was to use the \Drupal\patternkit\Entity\Pattern::create() method. The new patternkit.pattern.repository service provides a method to get the pattern entity directly and should be used for this instead:

$pattern = \Drupal::service('patternkit.pattern.repository')
  ->getPattern('@patternkit/atoms/example/src/example');
$schema = $pattern->getSchema();

Loading a bundled schema

If a pattern's schema is needed with all dependencies included, the patternkit.pattern.repository service may also be used for this.

$pattern = \Drupal::service('patternkit.pattern.repository')
  ->getPattern('@patternkit/atoms/example/src/example', TRUE);
$schema_json = $pattern->getSchema();

Sample Schema: @my/example/pattern

{
  "type": "object",
  "properties": {
    "my_text_property": {
      "$ref": "@my/text/pattern"
    }
  }
}

Sample Schema: @my/text/pattern

{
  "type": "string"
} 

Bundled Schema

{
  "type": "object",
  "properties": {
    "my_text_property": {
      "$ref": "#/definitions/my_text_pattern"
    }
  },
  "definitions": {
    "my_text_pattern": {
      "type": "string"
    }
  }
}

Listing all discovered patterns

If only a list of discovered patterns is needed, it is no longer necessary to load and iterate through all discovered pattern definitions. The patternkit.pattern.repository service provides a new method for retrieving a list of only the names of all known patterns:

$patternRepository = \Drupal::service('patternkit.pattern.repository');
foreach ($patternRepository->getAllPatternNames() as $pattern) {
  // Do something with each pattern.
}

Library parsing

The following services and plugins work with the library definitions, as discovered and processed by the Library Namespace Resolver service, to parse pattern library definitions defined in an extension's *.libraries.yml file and discover available patterns for usage.

Patternkit Library Parsers (patternkit.asset.library.parser.*)

Library parser plugins are used to interpret configuration values from a library's `patterns` key, and load pattern definitions for usage by Patternkit. When a Pattern is being fetched or rendered, the parser plugin is used to complete these tasks.

Pattern Library Plugin Manager (plugin.manager.library.pattern)

A plugin manager for pattern library parser plugins. This is the gateway to loading parser plugins as specified by a given pattern definition.

Schema processing

These services are largely internal to the operations of the Patternkit module, but when one needs to work directly with the schema content or configuration being fed into it, these services may be helpful. They all heavily leverage the swaggest/json-schema library to parse and process pattern schemas in various ways.

Pattern Field Processor Plugin Manager (plugin.manager.pattern_field_processor)

Schema Factory (patternkit.schema.schema_factory)

A service to create usable Schema objects using the swaggest/json-schema library for validation or other processing operations. Using this service to create schemas will help to ensure consistency in configuration options, and abstraction should any other elements of the schema instantiation process change.

Schema Context Builder (patternkit.schema.context_builder)

A service split out from the recently introduced patternkit.schema.schema_factory service. This service is responsible for assembling and configuring Schema operation contexts consistently with necessary default options.

Schema Ref Handler (patternkit.schema.ref_handler)

A utility service for processing and manipulating references discovered within pattern schemas.

Schema Walker Factory ( patternkit.schema.schema_walker_factory)

A factory service used by the Pattern Field Processor Plugin Manager for traversal of schemas with schema data. This allows available Pattern Field Processor plugins to be applied to the individual values and properties of a Pattern's configuration alongside the schema data for that property.

Schema Data PreProcessors (patternkit.schema.data_preprocessor.*)

Schema data PreProcessors are a tool derived within the swaggest/json-schema library to allow schema data to be processed prior to assignment or validation within a Schema instance. The Patternkit module uses these to perform various operations on schemas themselves, as well as data being processed into schemas.

Schema Data PreProcessor Factory (patternkit.schema.data_preprocessor.factory)

A factory service for instantiating schema DataPreProcessor utilities used in schema contexts for a variety of processing tasks.

Object Coercion Data PreProcessor (patternkit.schema.data_preprocessor.objects)

This preprocessor adds flexibility for how JSON schemas are handled since PHP decoding JSON may either cast objects to associative arrays or not depending on the flags passed to it. When in use, this data preprocessor checks the schema property being tested to determine if it expects an object, and if necessary will cast an associative array to match.

Reference Bundler Data PreProcessor (patternkit.schema.data_preprocessor.bundler)

This preprocessor is used to rewrite references within a schema to point to bundled schema definitions instead of external references. This is a key part of the dependency bundling process to ensure requests outside the schema are no longer necessary.

Reference Normalizer Data PreProcessor (patternkit.schema.data_preprocessor.normalizer)

In the case bundling is not used in schemas, namespaced pattern references within pattern schemas are rewritten to request and load through a Patternkit controller at /api/patternkit. For example, this data preprocessor rewrites a discovered namespaced reference @patternkit/atoms/example/src/example to /api/patternkit/patternkit/atoms/example/src/example?asset=schema. With this rewritten, if the JSON Editor encounters this reference it will request the referenced schema asynchronously from the Patternkit controller.

Reference Observer Data PreProcessor (patternkit.schema.data_preprocessor.ref_observer)

This data preprocessor performs no manipulation of the schema being loaded, but it instead records any references it encounters. This is key to the process of discovering references and dependencies within pattern schemas.

Asset management

Library Stream Wrapper (stream_wrapper.library)

A public stream wrapper service registering the library:// stream for accessing file assets within a library.

Pattern Stream Wrapper (stream_wrapper.patternkit)

A public stream wrapper service registering the patternkit:// stream for accessing patternkit files.

Patternkit Twig Loader (twig.loader.patternlibrary)

A twig file loader that iterates through all discovered library definitions and registers the path and namespace for any pattern libraries it finds.