Sabre\Xml\Service Class Reference

XML parsing and writing service. More...

Inheritance diagram for Sabre\Xml\Service:

Collaboration diagram for Sabre\Xml\Service:

Public Member Functions
	getReader ()
	Returns a fresh XML Reader. More...
	getWriter ()
	Returns a fresh xml writer. More...
	parse ($input, $contextUri=null, &$rootElementName=null)
	Parses a document in full. More...
	expect ($rootElementName, $input, $contextUri=null)
	Parses a document in full, and specify what the expected root element name is. More...
	write ($rootElementName, $value, $contextUri=null)
	Generates an XML document in one go. More...
	mapValueObject ($elementName, $className)
	Map an xml element to a PHP class. More...
	writeValueObject ($object, $contextUri=null)
	Writes a value object. More...

Static Public Member Functions
static	parseClarkNotation ($str)
	Parses a clark-notation string, and returns the namespace and element name components. More...

Data Fields
	$elementMap = []
	$namespaceMap = []
	$classMap = []

Protected Attributes
	$valueObjectMap = []
	A list of classes and which XML elements they map to. More...

Detailed Description

XML parsing and writing service.

You are encouraged to make a instance of this for your application and potentially extend it, as a central API point for dealing with xml and configuring the reader and writer.

Copyright

Copyright (C) 2009-2015 fruux GmbH (https://fruux.com/).

Author

Evert Pot (http://evertpot.com/) http://sabre.io/license/ Modified BSD License

Definition at line 16 of file Service.php.

Member Function Documentation

expect()

Sabre\Xml\Service::expect	(		$rootElementName,
			$input,
			$contextUri = null
	)

Parses a document in full, and specify what the expected root element name is.

This function works similar to parse, but the difference is that the user can specify what the expected name of the root element should be, in clark notation.

This is useful in cases where you expected a specific document to be passed, and reduces the amount of if statements.

It's also possible to pass an array of expected rootElements if your code may expect more than one document type.

Parameters

	string|string[]	$rootElementName
string | resource	$input
string | null	$contextUri

Returns

void

Definition at line 143 of file Service.php.

References Sabre\Xml\$contextUri, $input, $r, $result, and Sabre\Xml\Service\getReader().

                                                                  {

        if (is_resource($input)) {
            // Unfortunately the XMLReader doesn't support streams. When it
            // does, we can optimize this.
            $input = stream_get_contents($input);
        }
        $r = $this->getReader();
        $r->contextUri = $contextUri;
        $r->xml($input);

        $rootElementName = (array)$rootElementName;

        foreach ($rootElementName as &$rEl) {
            if ($rEl[0] !== '{') $rEl = '{}' . $rEl;
        }

        $result = $r->parse();
        if (!in_array($result['name'], $rootElementName, true)) {
            throw new ParseException('Expected ' . implode(' or ', (array)$rootElementName) . ' but received ' . $result['name'] . ' as the root element');
        }
        return $result['value'];

    }

Here is the call graph for this function:

getReader()

Sabre\Xml\Service::getReader

(

)

Returns a fresh XML Reader.

Returns

Reader

Definition at line 66 of file Service.php.

References Sabre\Xml\Service\$elementMap, and $r.

Referenced by Sabre\Xml\Service\expect(), and Sabre\Xml\Service\parse().

                         {

        $r = new Reader();
        $r->elementMap = $this->elementMap;
        return $r;

    }

Here is the caller graph for this function:

getWriter()

Sabre\Xml\Service::getWriter

(

)

Returns a fresh xml writer.

Returns

Writer

Definition at line 79 of file Service.php.

References Sabre\Xml\Service\$classMap, Sabre\Xml\Service\$namespaceMap, and $w.

Referenced by Sabre\Xml\Service\write().

                         {

        $w = new Writer();
        $w->namespaceMap = $this->namespaceMap;
        $w->classMap = $this->classMap;
        return $w;

    }

Here is the caller graph for this function:

mapValueObject()

Sabre\Xml\Service::mapValueObject	(		$elementName,
			$className
	)

Map an xml element to a PHP class.

Calling this function will automatically setup the Reader and Writer classes to turn a specific XML element to a PHP class.

For example, given a class such as :

class Author { public $firstName; public $lastName; }

and an XML element such as:

<author xmlns="http://example.org/ns"> <firstName>...</firstName> <lastName>...</lastName> </author>

These can easily be mapped by calling:

$service->mapValueObject('{http://example.org}author', 'Author');

Parameters

string	$elementName
object	$className

Returns

void

Definition at line 226 of file Service.php.

References $namespace, $reader, and Sabre\Xml\Deserializer\valueObject().

                                                      {
        list($namespace) = self::parseClarkNotation($elementName);

        $this->elementMap[$elementName] = function(Reader $reader) use ($className, $namespace) {
            return \Sabre\Xml\Deserializer\valueObject($reader, $className, $namespace);
        };
        $this->classMap[$className] = function(Writer $writer, $valueObject) use ($namespace) {
            return \Sabre\Xml\Serializer\valueObject($writer, $valueObject, $namespace);
        };
        $this->valueObjectMap[$className] = $elementName;
    }

Here is the call graph for this function:

parse()

Sabre\Xml\Service::parse	(		$input,
			$contextUri = null,
		&	$rootElementName = null
	)

Parses a document in full.

Input may be specified as a string or readable stream resource. The returned value is the value of the root document.

Specifying the $contextUri allows the parser to figure out what the URI of the document was. This allows relative URIs within the document to be expanded easily.

The $rootElementName is specified by reference and will be populated with the root element name of the document.

Parameters

string | resource	$input
string | null	$contextUri
string | null	$rootElementName

Exceptions

ParseException

Returns

array|object|string

Definition at line 107 of file Service.php.

References Sabre\Xml\$contextUri, $input, $r, $result, and Sabre\Xml\Service\getReader().

                                                                         {

        if (is_resource($input)) {
            // Unfortunately the XMLReader doesn't support streams. When it
            // does, we can optimize this.
            $input = stream_get_contents($input);
        }
        $r = $this->getReader();
        $r->contextUri = $contextUri;
        $r->xml($input);

        $result = $r->parse();
        $rootElementName = $result['name'];
        return $result['value'];

    }

Here is the call graph for this function:

parseClarkNotation()

static Sabre\Xml\Service::parseClarkNotation (   $str )

static

Parses a clark-notation string, and returns the namespace and element name components.

If the string was invalid, it will throw an InvalidArgumentException.

Parameters

string

$str

Exceptions

InvalidArgumentException

Returns

array

Definition at line 274 of file Service.php.

Referenced by Sabre\VObject\Parser\XML\getTagName(), Sabre\VObject\Parser\XML\parseProperties(), Sabre\DAV\Client\propFind(), Sabre\Xml\Writer\startElement(), Sabre\Xml\ServiceTest\testParseClarkNotation(), Sabre\Xml\ServiceTest\testParseClarkNotationFail(), and Sabre\Xml\Writer\writeAttribute().

                                             {
        static $cache = [];

        if (!isset($cache[$str])) {

            if (!preg_match('/^{([^}]*)}(.*)$/', $str, $matches)) {
                throw new \InvalidArgumentException('\'' . $str . '\' is not a valid clark-notation formatted string');
            }

            $cache[$str] = [
                $matches[1],
                $matches[2]
            ];
        }

        return $cache[$str];
    }

Here is the caller graph for this function:

write()

Sabre\Xml\Service::write	(		$rootElementName,
			$value,
			$contextUri = null
	)

Generates an XML document in one go.

The $rootElement must be specified in clark notation. The value must be a string, an array or an object implementing XmlSerializable. Basically, anything that's supported by the Writer object.

$contextUri can be used to specify a sort of 'root' of the PHP application, in case the xml document is used as a http response.

This allows an implementor to easily create URI's relative to the root of the domain.

Parameters

string	$rootElementName
string | array | XmlSerializable	$value
string | null	$contextUri

Definition at line 186 of file Service.php.

References Sabre\Xml\$contextUri, $w, and Sabre\Xml\Service\getWriter().

Referenced by Sabre\Xml\Service\writeValueObject().

                                                                 {

        $w = $this->getWriter();
        $w->openMemory();
        $w->contextUri = $contextUri;
        $w->setIndent(true);
        $w->startDocument();
        $w->writeElement($rootElementName, $value);
        return $w->outputMemory();

    }

Here is the call graph for this function:

Here is the caller graph for this function:

writeValueObject()

Sabre\Xml\Service::writeValueObject	(		$object,
			$contextUri = null
	)

Writes a value object.

This function largely behaves similar to write(), except that it's intended specifically to serialize a Value Object into an XML document.

The ValueObject must have been previously registered using mapValueObject().

Parameters

object	$object
string	$contextUri

Returns

void

Definition at line 251 of file Service.php.

References Sabre\Xml\$contextUri, and Sabre\Xml\Service\write().

                                                           {

        if (!isset($this->valueObjectMap[get_class($object)])) {
            throw new \InvalidArgumentException('"' . get_class($object) . '" is not a registered value object class. Register your class with mapValueObject.');
        }
        return $this->write(
            $this->valueObjectMap[get_class($object)],
            $object,
            $contextUri
        );

    }

Here is the call graph for this function:

Field Documentation

$classMap

Sabre\Xml\Service::$classMap = []

Definition at line 59 of file Service.php.

Referenced by Sabre\Xml\Service\getWriter().

$elementMap

Sabre\Xml\Service::$elementMap = []

Definition at line 29 of file Service.php.

Referenced by Sabre\Xml\Service\getReader().

$namespaceMap

Sabre\Xml\Service::$namespaceMap = []

Definition at line 39 of file Service.php.

Referenced by Sabre\Xml\Service\getWriter().

$valueObjectMap

Sabre\Xml\Service::$valueObjectMap = []

protected

A list of classes and which XML elements they map to.

Definition at line 295 of file Service.php.

---

The documentation for this class was generated from the following file:

• libs/composer/vendor/sabre/xml/lib/Service.php