marienfressinaud / lib_opml
A library to read and write OPML in PHP.
Requires
- php: >=7.2.0
- ext-dom: *
Requires (Dev)
- phpunit/phpunit: ^8
- squizlabs/php_codesniffer: ^3.6
This package is not auto-updated.
Last update: 2024-10-04 23:31:14 UTC
README
lib_opml is a library to read and write OPML in PHP.
OPML is a standard designed to store and exchange outlines (i.e. a tree structure arranged to show hierarchical relationships). It is mainly used to exchange list of feeds between feed aggregators. The specification is available at opml.org.
lib_opml has been tested with PHP 7.2+. It requires DOMDocument to work.
It supports versions 1.0 and 2.0 of OPML since these are the only published versions. Version 1.1 is treated as version 1.0, as stated by the specification.
It is licensed under the MIT license.
Installation
lib_opml is available on Packagist and it is recommended to install it with Composer:
$ composer require marienfressinaud/lib_opml
If you don’t use Composer, you can download the ZIP archive
and copy the content of the src/
folder in your project. Then, load the files
manually:
<?php
require 'path/to/lib_opml/LibOpml/Exception.php';
require 'path/to/lib_opml/LibOpml/LibOpml.php';
require 'path/to/lib_opml/functions.php';
Usage
Parse OPML
Let’s say that you have an OPML file named my_opml_file.xml
:
<?xml version="1.0" encoding="UTF-8" ?>
<opml version="2.0">
<head>
<title>My OPML</title>
</head>
<body>
<outline text="Newspapers">
<outline text="El País" />
<outline text="Le Monde" />
<outline text="The Guardian" />
<outline text="The New York Times" />
</outline>
</body>
</opml>
You can load it with:
$opml_array = libopml_parse_file('my_opml_file.xml');
lib_opml parses the file and returns an array:
[
'version' => '2.0',
'namespaces' => [],
'head' => [
'title' => 'My OPML'
],
'body' => [ // each entry of the body is an outline
[
'text' => 'Newspapers',
'@outlines' => [ // sub-outlines are accessible with the @outlines key
['text' => 'El País'],
['text' => 'Le Monde'],
['text' => 'The Guardian'],
['text' => 'The New York Times']
]
]
]
]
Since it's just an array, it's very simple to manipulate:
foreach ($opml_array['body'] as $outline) {
echo $outline['text'];
}
You also can load directly an OPML string:
$opml_string = '<opml>...</opml>';
$opml_array = libopml_parse_string($opml_string);
Render OPML
lib_opml is able to render an OPML string from an array. It checks that the data is valid and respects the specification.
$opml_array = [
'head' => [
'title' => 'My OPML',
],
'body' => [
[
'text' => 'Newspapers',
'@outlines' => [
['text' => 'El País'],
['text' => 'Le Monde'],
['text' => 'The Guardian'],
['text' => 'The New York Times']
]
]
]
];
$opml_string = libopml_render($opml_array);
file_put_contents('my_opml_file.xml', $opml_string);
Handle errors
If rendering (or parsing) fails for any reason (e.g. empty body
, missing
text
attribute, wrong element type), a \marienfressinaud\LibOpml\Exception
is raised:
try {
$opml_array = libopml_render([
'body' => []
]);
} catch (\marienfressinaud\LibOpml\Exception $e) {
echo $e->getMessage();
}
Class style
lib_opml can also be used with a class style:
use marienfressinaud\LibOpml;
$libopml = new LibOpml\LibOpml();
$opml_array = $libopml->parseFile($filename);
$opml_array = $libopml->parseString($opml_string);
$opml_string = $libopml->render($opml_array);
Special elements and attributes
Some elements have special meanings according to the specification, which means they can be parsed to a specific type by lib_opml. In the other way, when rendering an OPML string, you must pass these elements with their correct types.
Head elements:
dateCreated
is parsed to a\DateTime
;dateModified
is parsed to a\DateTime
;expansionState
is parsed to an array of integers;vertScrollState
is parsed to an integer;windowTop
is parsed to an integer;windowLeft
is parsed to an integer;windowBottom
is parsed to an integer;windowRight
is parsed to an integer.
Outline attributes:
created
is parsed to a\DateTime
;category
is parsed to an array of strings;isComment
is parsed to a boolean;isBreakpoint
is parsed to a boolean.
If one of these elements is not of the correct type, an Exception is raised.
Finally, there are additional checks based on the outline type attribute:
- if
type="rss"
, then thexmlUrl
attribute is required; - if
type="link"
, then theurl
attribute is required; - if
type="include"
, then theurl
attribute is required.
Note that the type
attribute is case-insensitive and will always be lowercased.
Namespaces
OPML can be extended with namespaces:
An OPML file may contain elements and attributes not described on this page, only if those elements are defined in a namespace, as specified by the W3C.
When rendering an OPML, you can include a namespaces
key to specify
namespaces:
$opml_array = [
'namespaces' => [
'test' => 'https://example.com/test',
],
'body' => [
['text' => 'My outline', 'test:path' => '/some/example/path'],
],
];
$opml_string = libopml_render($opml_array);
echo $opml_string;
This will output:
<?xml version="1.0" encoding="UTF-8"?>
<opml xmlns:test="https://example.com/test" version="2.0">
<head/>
<body>
<outline text="My outline" test:path="/some/example/path"/>
</body>
</opml>
Strictness
You can tell lib_opml to be less or more strict when parsing or rendering OPML.
This is done by passing an optional $strict
attribute to the functions. When
strict is false
, most of the specification requirements are simply ignored
and lib_opml will do its best to parse (or generate) an OPML.
By default, parsing is not strict so you’ll be able to read most of the files
out there. If you want the parsing to be strict (to validate a file for
instance), pass true
to libopml_parse_file()
or libopml_parse_string()
:
$opml_array = libopml_parse_file($filename, true);
$opml_array = libopml_parse_string($opml_string, true);
On the other side, reading is strict by default, so you are encouraged to
generate valid OPMLs. If you need to relax the strictness, pass false
to
libopml_render()
:
$opml_string = libopml_render($opml_array, false);
Please note that when using the class form, strict is passed during the object instantiation:
use marienfressinaud\LibOpml;
// lib_opml will be strict for both parsing and rendering!
$libopml = new LibOpml\LibOpml(true);
$opml_array = $libopml->parseString($opml_string);
$opml_string = $libopml->render($opml_array);
Examples and documented source code
See the examples/
folder for concrete examples.
You are encouraged to read the source code to learn more about lib_opml. Thus, the full documentation is available as comments in the code:
Changelog
See CHANGELOG.md.
Support and stability
Today, lib_opml covers all the aspects of the OPML specification. Since the spec didn't change for more than 15 years, it is expected for the library to not change a lot in the future. Thus, I plan to release the v1.0 in a near future. I'm only waiting for more tests to be done on its latest version (in particular in FreshRSS, see FreshRSS/FreshRSS#4403). I would also wait for clarifications about the specification (see scripting/opml.org#3), but it isn't a hard requirement.
After the release of 1.0, lib_opml will be considered as “finished”. This means I will not add new features, nor break the existing code. However, I commit myself to continue to support the library to fix security issues, bugs, or to add support to new PHP versions.
In consequence, you can expect lib_opml to be stable.
Tests and linters
This section is for developers of lib_opml.
To run the tests, you’ll have to install Composer first (see the official documentation). Then, install the dependencies:
$ make install
You should now have a vendor/
folder containing the development dependencies.
Run the tests with:
$ make test
Run the linter with:
$ make lint
$ make lint-fix
Contributing
Please submit bug reports and merge requests to the Framagit repository.
There’s not a lot to do, but the documentation and examples could probably be improved.
Merge requests require that you fill a short checklist to save me time while reviewing your changes. You also must make sure the test suite succeeds.