Global navigation

   Documentation Center
   eZ Studio & eZ Platform
     User Manual
     Technical Manual
     Glossary
   eZ Publish 4.x / legacy

 
eZ Publish (5.x)

eZ Publish 5.x | For eZ Platform & eZ Studio topics see Technical manual and User manual, for eZ Publish 4.x and Legacy topics see eZ Publish legacy

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Let's create our visitor next. It must extend the eZ\Publish\Core\REST\Common\Output\ValueObjectVisitor abstract class, and implement the visit() method.
It will receive as arguments:

  • $visitor: The output visitor. Can be used to set custom response headers ( setHeader( $name, $value )), HTTP status code ( setStatus( $statusCode ) )...
  • $generator: The actual Response generator. It provides you with a DOM like API.
  • $data: the visited data, the exact object you returned from the controller 
Code Block
languagephp
titleMy/Bundle/RestBundle/Rest/Controller/Default.php
namespace My\Bundle\RestBundle\Rest\ValueObjectVisitor;


use eZ\Publish\Core\REST\Common\Output\ValueObjectVisitor;
use eZ\Publish\Core\REST\Common\Output\Generator;
use eZ\Publish\Core\REST\Common\Output\Visitor;


class Hello extends ValueObjectVisitor
{
    public function visit( Visitor $visitor, Generator $generator, $data )
    {
        $this->generator->startValueElement( 'Hello', $data->name );
        $this->generator->endValueElement( 'Hello' );
    }
}

Do not hesitate to look into the built-in ValueObjectVisitors, in eZ/Publish/Core/REST/Server/Output/ValueObjectVisitor, for more examples.

Input parser

What we have seen above covers requests that don't require an input payload, such as GET or DELETE. If you need to provide your controller with parameters, either in JSON or XML, the parameter struct requires an Input Parser so that the payload can be converted to an actual ValueObject.

Each payload is dispatched to its Input Parser based on the request's Content-Type header. For example, a request with a Content-Type of application/vnd.ez.api.ContentCreate will be parsed by eZ\Publish\Core\REST\Server\Input\Parser\ContentCreate. This parser will build and return a ContentCreateStruct that can then be used to create content with the Public API.

Those input parsers are provided with a pre-parsed version of the input payload, as an associative array, and don't have to care about the actual format (XML or JSON).

Let's see what it would look like with a Content-Type of application/vnd.my.Greetings, that would send this as XML:

Code Block
languagehtml/xml
titleapplication/vnd.my.Greetings+xml
<?xml version="1.0" encoding="utf-8"?>
<Greetings>
    <name>John doe</name>
</Greetings>

First, we need to create a service with the appropriate tag in services.yml.

Code Block
titlesrc/My/Bundle/RestBundle/Resources/config/services.yml
services:
    myRestBundle.input_parser.Greetings:
        parent: ezpublish_rest.input.parser
        class: My\Bundle\RestBundle\Rest\InputParser\Greetings
        tags:
            - { name: ezpublish_rest.input.parser, mediaType: application/vnd.ez.my.Greetings }

The mediaType attribute of the ezpublish_rest.input.parser tag maps our Content Type to the input parser.

Let's implement our parser. It must extend eZ\Publish\Core\REST\Server\Input\Parser, and implement the parse() method. It accepts as an argument the input payload, $data, as an array, and an instance of ParsingDispatcher that can be used to forward parsing of embedded content.

For convenience, we will consider that our input parser returns an instance of our Value\Hello class.

Code Block
languagephp
titleMy/Bundle/RestBundle/Rest/InputParser/Greetings.php
namespace My\Bundle\RestBundle\InputParser;
 
use eZ\Publish\Core\REST\Server\Input\Parser\Base as BaseParser;
use eZ\Publish\Core\REST\Common\Input\ParsingDispatcher;
use My\Bundle\RestBundle\Rest\Value\Hello;
use eZ\Publish\Core\REST\Common\Exceptions;


class Greetings extends BaseParser
{
    /**
     * @return My\Bundle\RestBundle\Rest\Value\Hello
    public function parse( array $data, ParsingDispatcher $parsingDispatcher )
	{
        // re-using the REST exceptions will make sure that those already have a ValueObjectVisitor
        if ( !array_key_exists( 'name', $data ) )
            throw new Exceptions\Parser( "Missing or invalid 'name' element for Greetings." );


        // the root level of the parsed structure is ignored
        $name = $data['name']
 
        return new Hello( $name );
	}
}

Do not hesitate to look into the built-in InputParsers, in eZ/Publish/Core/REST/Server/Input/Parser, for more examples.