Download the PHP package gdbots/pbjx-bundle without Composer

pbjx-bundle-php

Symfony bundle that integrates gdbots/pbjx library.

Configuration

Follow the standard bundle install using gdbots/pbjx-bundle as the composer package name. The default configuration provides in memory processing for all send, publish, request operations. The EventStore and EventSearch are not configured by default.

The examples below assume you're running the DynamoDb EventStore and Elastica EventSearch. These are optional configurations.

config/packages/pbjx.yml:

In your local environment, it is highly recommended to configure the PbjxDebugger.

__config/services_local.yml:__

Pbjx HTTP Endpoints

Pbjx is ready to be used within your app and console commands but it's not yet available via HTTP. Providing the HTTP features is very powerful but can be very dangerous if you don't secure it correctly.

All of the usual rules apply when securing your app. Authentication and authorization is up to you, however, Symfony makes this fairly easy using the security components.

Example security configuration:

To enable Pbjx http endpoints you must include the routes. In config/routes.yml:

Once this is in place ANY pbjx messages can be sent to the endpoint /pbjx/vendor/package/category/message. This url is the configured prefix and then the SchemaCurie resolved to a url.

Why not just use /pbjx? It is a huge benefit to have the full path to the SchemaCurie for logging, authorization, load balancing, debugging, etc.

Example curl request:

Example ajax request:

If your SchemaCurie contains an empty category segment, use "_" in its place in the url.

Controllers

The recommended way to use Pbjx in a controller is to use Symfony dependency injection for the pbjx services you need and if necessary import the PbjxControllerTrait to get helper methods for rendering pbj into twig templates.

PbjxControllerTrait::renderPbj

This is a convenience method that accepts a pbj message and derives the template name using pbjTemplate and calls Symfony's render method (from framework bundle Controller).

The template will have pbj as a variable which is the message object itself.

TIP: {{ pbj }} will dump the message to yaml for easy debugging in twig, or {{ pbj|json_encode(constant('JSON_PRETTY_PRINT')) }}

PbjxControllerTrait::pbjTemplate

Returns a reference to a twig template based on the schema of the provided message (pbj schema). This allows for component style development for pbj messages. You are asking for a template that can render your message (e.g. Article) as a "card", "modal", "page", etc.

This can be combined with gdbots/app-bundle DeviceViewRendererTrait::renderUsingDeviceView (the renderPbj method does this automatically).

What you end up with is a namespaced path reference to a template which conforms to the Symfony template naming best practices. Examples:

Twig Extension

A few twig functions are provided to expose most of what controllers can do to your twig templates.

Twig Function: pbj_template

Returns a reference to a twig template based on the schema of the provided message (pbj schema). This allows for component style development for pbj messages. You are asking for a template that can render your message (e.g. Article) as a "card", "modal", "slackpost", etc. and optionally that template can be device view specific (card.smartphone.html.twig)_.

Example:

Twig Function: pbj_url

Returns a named URL to a pbj instance. This depends on gdbots/uri-template package which provides a way to register uri templates. These are expected to be in the format vendor:label.template_name, e.g. acme:article.canonical.

Example:

Twig Function: uri_template_expand

When you need to expand a URI template by id direct with your own variables, use this function.

Example:

Twig Function: pbjx_request

In the same way that you can embed a Symfony controller within twig you can embed a pbjx request in twig. This function performs a $pbjx->request($request); and returns the response. If debugging is enabled an exception will be thrown (generally in dev), otherwise it will be logged and null will be returned.

Example:

Console Commands

This library provides quite a few commands to make managing the services of Pbjx simple. Run the Symfony console and look for pbjx commands.

The most useful is probably going to be the pbjx and pbjx:batch commands. These run pbjx just like you do in your application code and return the resulting pbj.

Pbjx is designed to run the the same way via cli, application code and http.

Example response:

Review the --help on the pbjx commands for more details.

Library Development

Pbj has a concept of mixins which is just a schema that can be added to other schemas. This strategy is useful for creating consistent data structures and allowing for library development to be done against mixins and not concrete schemas.

A mixin cannot be used by itself to create messages, it must be added to a schema that is NOT a mixin.

This bundle provides a compiler pass that automatically registers handlers for pbjx command and requests.

Example:

Fictional WidgetCo makes widgets for websites by creating mixins and libraries to provide implementations for those mixins.

• WidgetCo has a mixin called widgetco:blog:mixin:add-comment
• WidgetCo has a handler called WidgetCo\Blog\AddCommentHandler that uses marker interface Gdbots\Pbjx\DependencyInjection\PbjxHandler.
• WidgetCo's handler uses the mixins findOne or findAll method to return all SchemaCurie objects it can handle.

Your company Acme now has a blog and wants to use WidgetCo mixins AND the implementation provided by WidgetCoBlogBundle.

• Acme creates a concrete schema called acme:blog:command:add-comment that uses the mixin widgetco:blog:mixin:add-comment
• When pbjx sends the command it will look for a service to handle acme:blog:command:add-comment curie.
• The service can be autoconfigured by symfony

You can still override if you want to extend or replace what widgetco provides by implementing your own handler using the PbjxHandler interface.

You can provide concrete schemas and implementations in libraries. There are pros and cons to both strategies, the biggest issue is that the schema is not as easily customized at the application level if the library is not developed using mixins.

Pbjx itself is a library built on mixins for Command, Request and Event messages.