/yaml

PHP library to load and parse YAML file to PHP datatypes equivalent

Primary LanguagePHPApache License 2.0Apache-2.0

Dallgoot : YAML library for PHP - Beta

Build Status PHP from Packagist Packagist Maintainability Scrutinizer Code Quality Code Coverage

PHP library to load and parse YAML file to coherent PHP datatypes equivalent

Dallgoot/Yaml Library

Installation

  • Dependencies are only useful for building documentation or for code contribution, so the "--update-no-dev" prevent from downloading and managing packages that you probably won't use.

You first need Composer and PHP ^8.1.14

composer require --update-no-dev dallgoot/yaml

Usage

See examples folder

Features

  • consistent PHP datatypes :
    • object for mappings
    • array for sequences
    • common scalars : string, integer, float, INF, NAN
    • JSON, DateTime(option), etc.
  • specific types (objects)
    • YamlObject for each Yaml content (multi-documents YAML is an array of YamlObject)
    • Compact for compact/short YAML syntax
    • Tagged object when tag is not determinable
  • recover from some parsing errors
  • tolerant to tabulations
  • debug levels :
    • 1 : print each line Node Type class and exit
    • 2 : print Loader global tree structure and exit
    • 3 : print each document NodeList and exit

Support

  • YAML specifications version 1.2
  • multi-line values (simple|double quoted or not, compact mapping|sequence or JSON)
  • multiple documents in a content (file or string)
  • compact syntax for mappings and sequences
  • comments (not yet implemented)
  • references (option : enabled by default)
  • tags with behaviour customization (overriding for common(CoreSchema), or specifying for custom) via implementing Tag/SchemaInterface.

What's different from other PHP Yaml libraries ?

YAML version supported coherent data types multiple documents JSON format validation complex mapping real reference behaviour custom tags handling
Symfony Yaml 1.2 ❌ ❌ ❌ ❌ ❌ ✔️
php-yaml 1.1 ❌ ✔️ ❌ ❌ ❌ ✔️
syck 1.0 ❌ ❌ ❌ ❌ ❌ ❌
spyc 1.0 ❌ ❌ ❌ ❌ ❌ ❌
Dallgoot/Yaml 1.2 ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
  • coherent data types (see coherence.md for explanations)
  • JSON format validation (Option, Note: if valid as per PHP function json_encode)
  • complex mapping (Note: keys are JSON formatted strings)
  • real reference behaviour : changing reference value modify other reference calls

Contributing

Only contributions concerning bug fixes will be review ATM. Requests for features will be dealt with after reading/writing YAML is considered bug free (and al current Options are implemented)

ToDo

  • Code coverage : target 100%
  • Benchmarks against other libs

Improvements

  • Examples of each function of the API
  • implement specific unit test for each YAML spec. invalid cases (what must not happen)
  • DUMPER:
    • implement/verify Dumper::Options
  • better/more precise errors identification (Yaml validation) with explanation in YAML content
  • Unicode checking (???)
  • OPTION : parse dates as PHP DateTime object
  • OPTION: Force renaming key names that are not valid PHP property name
  • TAG : function for 'php/object' that provides the correct namespace to build
  • NEON compatibility???
  • make immutable YamlObject

Performances

- TBD
- improved memory using SplFixedArray instead of regular arrays where possible

Sponsor

That is greatly appreciated : Buy Me A Coffee

Thanks