Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
<?php
/**
< * CFPropertyList < * {@link http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html Property Lists}
> * LICENSE > * > * This file is part of CFPropertyList. > * > * The PHP implementation of Apple's PropertyList can handle XML PropertyLists > * as well as binary PropertyLists. It offers functionality to easily convert > * data between worlds, e.g. recalculating timestamps from unix epoch to apple > * epoch and vice versa. A feature to automagically create (guess) the plist > * structure from a normal PHP data structure will help you dump your data to > * plist in no time. > * > * Copyright (c) 2018 Teclib' > * > * Permission is hereby granted, free of charge, to any person obtaining a copy > * of this software and associated documentation files (the "Software"), to deal > * in the Software without restriction, including without limitation the rights > * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell > * copies of the Software, and to permit persons to whom the Software is > * furnished to do so, subject to the following conditions: > * > * The above copyright notice and this permission notice shall be included in all > * copies or substantial portions of the Software. > * > * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR > * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, > * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE > * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER > * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, > * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE > * SOFTWARE. > * > * ------------------------------------------------------------------------------
* @author Rodney Rehm <rodney.rehm@medialize.de> * @author Christian Kruse <cjk@wwwtech.de>
> * @copyright Copyright © 2018 Teclib
* @package plist
< * @version $Id$ < * @example example-read-01.php Read an XML PropertyList < * @example example-read-02.php Read a Binary PropertyList < * @example example-read-03.php Read a PropertyList without knowing the type < * @example example-create-01.php Using the CFPropertyList API < * @example example-create-02.php Using {@link CFTypeDetector} < * @example example-create-03.php Using {@link CFTypeDetector} with {@link CFDate} and {@link CFData} < * @example example-modify-01.php Read, modify and save a PropertyList
> * @license MIT > * @link https://github.com/TECLIB/CFPropertyList/ > * @link http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html Property Lists
*/ namespace CFPropertyList;
< use \Iterator, \DOMDocument, \DOMException, DOMImplementation, DOMNode;
< /** < * Require IOException, PListException, CFType and CFBinaryPropertyList < */ < require_once(__DIR__.'/IOException.php'); < require_once(__DIR__.'/PListException.php'); < require_once(__DIR__.'/CFType.php'); < require_once(__DIR__.'/CFBinaryPropertyList.php'); < require_once(__DIR__.'/CFTypeDetector.php');
> use Iterator; > use DOMDocument; > use DOMException; > use DOMImplementation; > use DOMNode;
/** * Property List * Interface for handling reading, editing and saving Property Lists as defined by Apple.
< * @author Rodney Rehm <rodney.rehm@medialize.de> < * @author Christian Kruse <cjk@wwwtech.de> < * @package plist
* @example example-read-01.php Read an XML PropertyList * @example example-read-02.php Read a Binary PropertyList * @example example-read-03.php Read a PropertyList without knowing the type * @example example-create-01.php Using the CFPropertyList API
< * @example example-create-02.php Using {@link CFTypeDetector} < * @example example-create-03.php Using {@link CFTypeDetector} with {@link CFDate} and {@link CFData} < * @example example-create-04.php Using and extended {@link CFTypeDetector}
> * @example example-create-02.php Using CFTypeDetector > * @example example-create-03.php Using CFTypeDetector with CFDate and CFData > * @example example-modify-01.php Read, modify and save a PropertyList > * ------------------------------------------------------------------------------
*/
< class CFPropertyList extends CFBinaryPropertyList implements Iterator {
> class CFPropertyList extends CFBinaryPropertyList implements Iterator > {
/** * Format constant for binary format * @var integer */ const FORMAT_BINARY = 1; /** * Format constant for xml format * @var integer */ const FORMAT_XML = 2; /** * Format constant for automatic format recognizing * @var integer */ const FORMAT_AUTO = 0; /** * Path of PropertyList * @var string */ protected $file = null; /** * Detected format of PropertyList * @var integer */ protected $detectedFormat = null; /** * Path of PropertyList * @var integer */ protected $format = null; /** * CFType nodes * @var array */ protected $value = array(); /** * Position of iterator {@link http://php.net/manual/en/class.iterator.php} * @var integer */ protected $iteratorPosition = 0; /** * List of Keys for numerical iterator access {@link http://php.net/manual/en/class.iterator.php} * @var array */ protected $iteratorKeys = null; /** * List of NodeNames to ClassNames for resolving plist-files * @var array */ protected static $types = array( 'string' => 'CFString', 'real' => 'CFNumber', 'integer' => 'CFNumber', 'date' => 'CFDate', 'true' => 'CFBoolean', 'false' => 'CFBoolean', 'data' => 'CFData', 'array' => 'CFArray', 'dict' => 'CFDictionary' ); /** * Create new CFPropertyList. * If a path to a PropertyList is specified, it is loaded automatically. * @param string $file Path of PropertyList * @param integer $format he format of the property list, see {@link FORMAT_XML}, {@link FORMAT_BINARY} and {@link FORMAT_AUTO}, defaults to {@link FORMAT_AUTO} * @throws IOException if file could not be read by {@link load()} * @uses $file for storing the current file, if specified * @uses load() for loading the plist-file */
< public function __construct($file=null,$format=self::FORMAT_AUTO) {
> public function __construct($file = null, $format = self::FORMAT_AUTO) > {
$this->file = $file; $this->format = $format; $this->detectedFormat = $format;
< if($this->file) $this->load();
> if ($this->file) { > $this->load(); > }
} /** * Load an XML PropertyList. * @param string $file Path of PropertyList, defaults to {@link $file} * @return void * @throws IOException if file could not be read * @throws DOMException if XML-file could not be read properly * @uses load() to actually load the file */
< public function loadXML($file=null) {
> public function loadXML($file = null) > {
$this->load($file,CFPropertyList::FORMAT_XML); } /** * Load an XML PropertyList. * @param resource $stream A stream containing the xml document. * @return void * @throws IOException if stream could not be read * @throws DOMException if XML-stream could not be read properly */
< public function loadXMLStream($stream) { < if(($contents = stream_get_contents($stream)) === FALSE) throw IOException::notReadable('<stream>');
> public function loadXMLStream($stream) > { > if (($contents = stream_get_contents($stream)) === false) { > throw IOException::notReadable('<stream>'); > }
$this->parse($contents,CFPropertyList::FORMAT_XML); } /** * Load an binary PropertyList. * @param string $file Path of PropertyList, defaults to {@link $file} * @return void * @throws IOException if file could not be read * @throws PListException if binary plist-file could not be read properly * @uses load() to actually load the file */
< public function loadBinary($file=null) {
> public function loadBinary($file = null) > {
$this->load($file,CFPropertyList::FORMAT_BINARY); } /** * Load an binary PropertyList. * @param stream $stream Stream containing the PropertyList * @return void * @throws IOException if file could not be read * @throws PListException if binary plist-file could not be read properly * @uses parse() to actually load the file */
< public function loadBinaryStream($stream) { < if(($contents = stream_get_contents($stream)) === FALSE) throw IOException::notReadable('<stream>');
> public function loadBinaryStream($stream) > { > if (($contents = stream_get_contents($stream)) === false) { > throw IOException::notReadable('<stream>'); > }
$this->parse($contents,CFPropertyList::FORMAT_BINARY); } /** * Load a plist file. * Load and import a plist file. * @param string $file Path of PropertyList, defaults to {@link $file} * @param integer $format The format of the property list, see {@link FORMAT_XML}, {@link FORMAT_BINARY} and {@link FORMAT_AUTO}, defaults to {@link $format} * @return void * @throws PListException if file format version is not 00 * @throws IOException if file could not be read * @throws DOMException if plist file could not be parsed properly * @uses $file if argument $file was not specified * @uses $value reset to empty array * @uses import() for importing the values */
< public function load($file=null,$format=null) {
> public function load($file = null, $format = null) > {
$file = $file ? $file : $this->file; $format = $format !== null ? $format : $this->format; $this->value = array();
< if(!is_readable($file)) throw IOException::notReadable($file);
> if (!is_readable($file)) { > throw IOException::notReadable($file); > }
switch($format) { case CFPropertyList::FORMAT_BINARY: $this->readBinary($file); break; case CFPropertyList::FORMAT_AUTO: // what we now do is ugly, but neccessary to recognize the file format $fd = fopen($file,"rb");
< if(($magic_number = fread($fd,8)) === false) throw IOException::notReadable($file);
> if (($magic_number = fread($fd, 8)) === false) { > throw IOException::notReadable($file); > }
fclose($fd); $filetype = substr($magic_number,0,6); $version = substr($magic_number,-2); if($filetype == "bplist") {
< if($version != "00") throw new PListException("Wrong file format version! Expected 00, got $version!");
> if ($version != "00") { > throw new PListException("Wrong file format version! Expected 00, got $version!"); > }
$this->detectedFormat = CFPropertyList::FORMAT_BINARY; $this->readBinary($file); break; } $this->detectedFormat = CFPropertyList::FORMAT_XML; // else: xml format, break not neccessary case CFPropertyList::FORMAT_XML: $doc = new DOMDocument();
< if(!$doc->load($file)) throw new DOMException();
> $prevXmlErrors = libxml_use_internal_errors(true); > libxml_clear_errors(); > if (!$doc->load($file)) { > $message = $this->getLibxmlErrors(); > libxml_clear_errors(); > libxml_use_internal_errors($prevXmlErrors); > throw new DOMException($message); > } > libxml_use_internal_errors($prevXmlErrors);
$this->import($doc->documentElement, $this); break; } } /** * Parse a plist string. * Parse and import a plist string. * @param string $str String containing the PropertyList, defaults to {@link $content} * @param integer $format The format of the property list, see {@link FORMAT_XML}, {@link FORMAT_BINARY} and {@link FORMAT_AUTO}, defaults to {@link $format} * @return void * @throws PListException if file format version is not 00 * @throws IOException if file could not be read * @throws DOMException if plist file could not be parsed properly * @uses $content if argument $str was not specified * @uses $value reset to empty array * @uses import() for importing the values */
< public function parse($str=NULL,$format=NULL) {
> public function parse($str = null, $format = null) > {
$format = $format !== null ? $format : $this->format; $str = $str !== null ? $str : $this->content;
> if ($str === null || strlen($str) === 0) { $this->value = array(); > throw IOException::readError(''); > }
switch($format) { case CFPropertyList::FORMAT_BINARY: $this->parseBinary($str); break; case CFPropertyList::FORMAT_AUTO: // what we now do is ugly, but neccessary to recognize the file format
< if(($magic_number = substr($str,0,8)) === false) throw IOException::notReadable("<string>");
> if (($magic_number = substr($str, 0, 8)) === false) { > throw IOException::notReadable("<string>"); > }
$filetype = substr($magic_number,0,6); $version = substr($magic_number,-2); if($filetype == "bplist") {
< if($version != "00") throw new PListException("Wrong file format version! Expected 00, got $version!");
> if ($version != "00") { > throw new PListException("Wrong file format version! Expected 00, got $version!"); > }
$this->detectedFormat = CFPropertyList::FORMAT_BINARY; $this->parseBinary($str); break; } $this->detectedFormat = CFPropertyList::FORMAT_XML; // else: xml format, break not neccessary case CFPropertyList::FORMAT_XML: $doc = new DOMDocument();
< if(!$doc->loadXML($str)) throw new DOMException();
> $prevXmlErrors = libxml_use_internal_errors(true); > libxml_clear_errors(); > if (!$doc->loadXML($str)) { > $message = $this->getLibxmlErrors(); > libxml_clear_errors(); > libxml_use_internal_errors($prevXmlErrors); > throw new DOMException($message); > } > libxml_use_internal_errors($prevXmlErrors);
$this->import($doc->documentElement, $this); break; } }
> protected function getLibxmlErrors() /** > { * Convert a DOMNode into a CFType. > return implode(', ', array_map(function (\LibXMLError $error) { * @param DOMNode $node Node to import children of > return trim("{$error->line}:{$error->column} [$error->code] $error->message"); * @param CFDictionary|CFArray|CFPropertyList $parent > }, libxml_get_errors())); * @return void > } */ >
< protected function import(DOMNode $node, $parent) {
> protected function import(DOMNode $node, $parent) > {
// abort if there are no children
< if(!$node->childNodes->length) return;
> if (!$node->childNodes->length) { > return; > }
foreach($node->childNodes as $n) { // skip if we can't handle the element
< if(!isset(self::$types[$n->nodeName])) continue;
> if (!isset(self::$types[$n->nodeName])) { > continue; > }
< $class = 'CFPropertyList\\'.self::$types[$n->nodeName];
> $class = __NAMESPACE__ . '\\'.self::$types[$n->nodeName];
$key = null; // find previous <key> if possible $ps = $n->previousSibling;
< while($ps && $ps->nodeName == '#text' && $ps->previousSibling) $ps = $ps->previousSibling;
> while ($ps && $ps->nodeName == '#text' && $ps->previousSibling) { > $ps = $ps->previousSibling; > }
// read <key> if possible
< if($ps && $ps->nodeName == 'key') $key = $ps->firstChild->nodeValue;
> if ($ps && $ps->nodeName == 'key') { > $key = $ps->firstChild->nodeValue; > }
switch($n->nodeName) { case 'date': $value = new $class(CFDate::dateValue($n->nodeValue)); break; case 'data': $value = new $class($n->nodeValue,true); break; case 'string': $value = new $class($n->nodeValue); break; case 'real': case 'integer': $value = new $class($n->nodeName == 'real' ? floatval($n->nodeValue) : intval($n->nodeValue)); break; case 'true': case 'false': $value = new $class($n->nodeName == 'true'); break; case 'array': case 'dict': $value = new $class(); $this->import($n, $value); if($value instanceof CFDictionary) { $hsh = $value->getValue(); if(isset($hsh['CF$UID']) && count($hsh) == 1) { $value = new CFUid($hsh['CF$UID']->getValue()); } } break; }
> if ($parent instanceof CFDictionary) {
// Dictionaries need a key
< if($parent instanceof CFDictionary) $parent->add($key, $value);
> $parent->add($key, $value); > } else {
// others don't
< else $parent->add($value);
> $parent->add($value); > }
} } /** * Convert CFPropertyList to XML and save to file. * @param string $file Path of PropertyList, defaults to {@link $file}
> * @param bool $formatted Print plist formatted (i.e. with newlines and whitespace indention) if true; defaults to false
* @return void * @throws IOException if file could not be read * @uses $file if $file was not specified */
< public function saveXML($file) { < $this->save($file,CFPropertyList::FORMAT_XML);
> public function saveXML($file, $formatted = false) > { > $this->save($file, CFPropertyList::FORMAT_XML, $formatted);
} /** * Convert CFPropertyList to binary format (bplist00) and save to file. * @param string $file Path of PropertyList, defaults to {@link $file} * @return void * @throws IOException if file could not be read * @uses $file if $file was not specified */
< public function saveBinary($file) {
> public function saveBinary($file) > {
$this->save($file,CFPropertyList::FORMAT_BINARY); } /** * Convert CFPropertyList to XML or binary and save to file. * @param string $file Path of PropertyList, defaults to {@link $file} * @param string $format Format of PropertyList, defaults to {@link $format}
> * @param bool $formatted_xml Print XML plist formatted (i.e. with newlines and whitespace indention) if true; defaults to false
* @return void * @throws IOException if file could not be read * @throws PListException if evaluated $format is neither {@link FORMAT_XML} nor {@link FORMAL_BINARY} * @uses $file if $file was not specified * @uses $format if $format was not specified */
< public function save($file=null,$format=null) {
> public function save($file = null, $format = null, $formatted_xml = false) > {
$file = $file ? $file : $this->file; $format = $format ? $format : $this->format;
< if($format == self::FORMAT_AUTO)$format = $this->detectedFormat;
> if ($format == self::FORMAT_AUTO) { > $format = $this->detectedFormat; > }
< if( !in_array( $format, array( self::FORMAT_BINARY, self::FORMAT_XML ) ) )
> if (!in_array($format, array( self::FORMAT_BINARY, self::FORMAT_XML ))) {
throw new PListException( "format {$format} is not supported, use CFPropertyList::FORMAT_BINARY or CFPropertyList::FORMAT_XML" );
> }
if(!file_exists($file)) { // dirname("file.xml") == "" and is treated as the current working directory
< if(!is_writable(dirname($file))) throw IOException::notWritable($file);
> if (!is_writable(dirname($file))) { > throw IOException::notWritable($file); > } > } elseif (!is_writable($file)) { > throw IOException::notWritable($file);
}
< else if(!is_writable($file)) throw IOException::notWritable($file);
< $content = $format == self::FORMAT_BINARY ? $this->toBinary() : $this->toXML();
> $content = $format == self::FORMAT_BINARY ? $this->toBinary() : $this->toXML($formatted_xml);
$fh = fopen($file, 'wb'); fwrite($fh,$content); fclose($fh); } /** * Convert CFPropertyList to XML * @param bool $formatted Print plist formatted (i.e. with newlines and whitespace indention) if true; defaults to false * @return string The XML content */
< public function toXML($formatted=false) {
> public function toXML($formatted = false) > {
$domimpl = new DOMImplementation(); // <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> $dtd = $domimpl->createDocumentType('plist', '-//Apple//DTD PLIST 1.0//EN', 'http://www.apple.com/DTDs/PropertyList-1.0.dtd'); $doc = $domimpl->createDocument(null, "plist", $dtd); $doc->encoding = "UTF-8"; // format output if($formatted) { $doc->formatOutput = true; $doc->preserveWhiteSpace = true; } // get documentElement and set attribs $plist = $doc->documentElement; $plist->setAttribute('version', '1.0'); // add PropertyList's children $plist->appendChild($this->getValue(true)->toXML($doc)); return $doc->saveXML(); } /************************************************************************************************ * M A N I P U L A T I O N ************************************************************************************************/ /** * Add CFType to collection. * @param CFType $value CFType to add to collection * @return void * @uses $value for adding $value */
< public function add(CFType $value=null) {
> public function add(CFType $value = null) > {
// anything but CFType is null, null is an empty string - sad but true
< if( !$value )
> if (!$value) {
$value = new CFString();
> }
$this->value[] = $value; } /** * Get CFType from collection. * @param integer $key Key of CFType to retrieve from collection * @return CFType CFType found at $key, null else * @uses $value for retrieving CFType of $key */
< public function get($key) { < if(isset($this->value[$key])) return $this->value[$key];
> public function get($key) > { > if (isset($this->value[$key])) { > return $this->value[$key]; > }
return null; } /** * Generic getter (magic) * * @param integer $key Key of CFType to retrieve from collection * @return CFType CFType found at $key, null else * @author Sean Coates <sean@php.net> * @link http://php.net/oop5.overloading */
< public function __get($key) {
> public function __get($key) > {
return $this->get($key); } /** * Remove CFType from collection. * @param integer $key Key of CFType to removes from collection * @return CFType removed CFType, null else * @uses $value for removing CFType of $key */
< public function del($key) {
> public function del($key) > {
if(isset($this->value[$key])) { $t = $this->value[$key]; unset($this->value[$key]); return $t; } return null; } /** * Empty the collection * @return array the removed CFTypes * @uses $value for removing CFType of $key */
< public function purge() {
> public function purge() > {
$t = $this->value; $this->value = array(); return $t; } /** * Get first (and only) child, or complete collection.
< * @param string $cftype if set to true returned value will be CFArray instead of an array in case of a collection
> * @param boolean $cftype if set to true returned value will be CFArray instead of an array in case of a collection
* @return CFType|array CFType or list of CFTypes known to the PropertyList * @uses $value for retrieving CFTypes */
< public function getValue($cftype=false) {
> public function getValue($cftype = false) > {
if(count($this->value) === 1) { $t = array_values( $this->value ); return $t[0]; } if($cftype) { $t = new CFArray(); foreach( $this->value as $value ) {
< if( $value instanceof CFType ) $t->add($value);
> if ($value instanceof CFType) { > $t->add($value); > }
} return $t; } return $this->value; } /** * Create CFType-structure from guessing the data-types. * The functionality has been moved to the more flexible {@link CFTypeDetector} facility. * @param mixed $value Value to convert to CFType * @param array $options Configuration for casting values [autoDictionary, suppressExceptions, objectToArrayMethod, castNumericStrings] * @return CFType CFType based on guessed type * @uses CFTypeDetector for actual type detection * @deprecated */
< public static function guess($value, $options=array()) {
> public static function guess($value, $options = array()) > {
static $t = null;
< if( $t === null )
> if ($t === null) {
$t = new CFTypeDetector( $options );
> }
return $t->toCFType( $value ); } /************************************************************************************************ * S E R I A L I Z I N G ************************************************************************************************/ /** * Get PropertyList as array. * @return mixed primitive value of first (and only) CFType, or array of primitive values of collection * @uses $value for retrieving CFTypes */
< public function toArray() {
> public function toArray() > {
$a = array();
< foreach($this->value as $value) $a[] = $value->toArray(); < if(count($a) === 1) return $a[0];
> foreach ($this->value as $value) { > $a[] = $value->toArray(); > } > if (count($a) === 1) { > return $a[0]; > }
return $a; } /************************************************************************************************ * I T E R A T O R I N T E R F A C E ************************************************************************************************/ /** * Rewind {@link $iteratorPosition} to first position (being 0) * @link http://php.net/manual/en/iterator.rewind.php * @return void * @uses $iteratorPosition set to 0 * @uses $iteratorKeys store keys of {@link $value} */
< public function rewind() {
> public function rewind(): void > {
$this->iteratorPosition = 0; $this->iteratorKeys = array_keys($this->value); } /** * Get Iterator's current {@link CFType} identified by {@link $iteratorPosition} * @link http://php.net/manual/en/iterator.current.php
< * @return CFType current Item
> * @return mixed current Item
* @uses $iteratorPosition identify current key * @uses $iteratorKeys identify current value */
< public function current() {
> #[\ReturnTypeWillChange] > public function current() > {
return $this->value[$this->iteratorKeys[$this->iteratorPosition]]; } /** * Get Iterator's current key identified by {@link $iteratorPosition} * @link http://php.net/manual/en/iterator.key.php
< * @return string key of the current Item
> * @return mixed key of the current Item
* @uses $iteratorPosition identify current key * @uses $iteratorKeys identify current value */
< public function key() {
> #[\ReturnTypeWillChange] > public function key() > {
return $this->iteratorKeys[$this->iteratorPosition]; } /** * Increment {@link $iteratorPosition} to address next {@see CFType} * @link http://php.net/manual/en/iterator.next.php * @return void * @uses $iteratorPosition increment by 1 */
< public function next() {
> public function next(): void > {
$this->iteratorPosition++; } /** * Test if {@link $iteratorPosition} addresses a valid element of {@link $value} * @link http://php.net/manual/en/iterator.valid.php * @return boolean true if current position is valid, false else * @uses $iteratorPosition test if within {@link $iteratorKeys} * @uses $iteratorPosition test if within {@link $value} */
< public function valid() {
> public function valid(): bool > {
return isset($this->iteratorKeys[$this->iteratorPosition]) && isset($this->value[$this->iteratorKeys[$this->iteratorPosition]]); }
<
} # eof