Download the PHP package sboden/odtphp without Composer

On this page you can find all versions of the php package sboden/odtphp. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package odtphp

ODTPHP

A PHP library for creating and manipulating ODT (OpenDocument Text) files.

Requirements

Installation

Install via Composer:

Basic Usage

Simple Variable Substitution

Advanced Usage with Images and Segments

Custom Properties

You can set custom document properties in your ODT file using the setCustomProperty() method:

Important notes about custom properties:

Examples:

Images

You can insert images into your ODT file using different measurement units:

Parameters for all image functions:

Note: While setImagePixel accepts measurements in pixels, the ODT format requires millimeters or centimeters internally. The function automatically converts pixel measurements to the appropriate format.

Error Handling

Testing

  1. Install dependencies:

  2. Run the tests:

On Linux:

On Windows:

You can also run the PHPUnit tests e.g. in PHPStorm, but you have to exclude the vendor directory to avoid warnings about the PHPUnit framework itself.

Test Structure

The test suite covers various aspects of the ODT templating functionality:

  1. Basic Tests (Basic1Test.php and Basic2Test.php):

    • Verify basic variable substitution in ODT templates
    • Test both PhpZip and PclZip ZIP handling methods
    • Demonstrate simple text replacement and encoding
  2. Configuration Tests (ConfigTest.php):

    • Validate configuration handling
    • Test custom delimiters
    • Check error handling for invalid configurations
  3. Edge Case Tests (EdgeCaseTest.php):

    • Handle complex scenarios like:
      • Large variable substitution
      • Nested segment merging
      • Special character encoding
      • Advanced image insertion
      • Invalid template handling
  4. Image Tests (ImageTest.php):

    • Verify image insertion functionality
    • Test image resizing
    • Check error handling for invalid image paths
  5. Variable Tests (VariableTest.php):

    • Test variable existence checks
    • Verify special character handling
    • Check multiline text substitution
  6. Custom Property Test (SetCustomPropertyTest.php):
    • Test custom propertyfunctionality

Each test is designed to ensure the robustness and reliability of the ODT templating library across different use cases and configurations.

A lot of tests run twice:

The tests generate ODT files and compare them with gold standard files located in:

Linting

On Linux:

Features

Configuration

Type Safety

This library is built with PHP 8.1's type system in mind:

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

The GPL-3.0 license is because of what the cybermonde/odtphp author put it to, I (sboden) don't want to change it. I don't consider odtphp to be "my" software, I only tried to make the cybermonde/odtphp fork work properly in PHP v8.3 and beyond.

Personally (sboden) I would have used an MIT or BSD license for odtphp, but I will happily abide with the original author's intent.

The original version/source code of odtphp is at https://sourceforge. net/projects/odtphp/. The cybermonde/odtphp fork I started from is at https://github. com/cybermonde/odtphp.

Usage justification

How and why we use odtphp in our projects.

Some of our projects send out letters (either PDF or on physical paper) to people: the idea is to have a nice template, fill in some data, create a PDF file from the filled-in template, and send the resulting PDF to the recipient.

The template is an ODT file, the data is stored in a database. We use odtphp to fill in the template. The filled-in ODT file is then transformed into a PDF file using (originally) jodconverter, and in newer projects using gotenberg.dev (which is essentially jodconverter using golang). The PDF converters run in a different container than the main applications.

The reason for using gotenberg over jodconverter is that gotenberg is better supported. And jodconverter was initially not able to handle large volumes since the most commonly used Docker container did not clean up after itself, so I had to build this in myself.

Why not generate PDFs directly from PHP? We tried, but it's difficult to have nice-looking PDFs using the existing PHP libraries. One PHP library has problems with images, another PHP PDF library faces issues with margins and headers/footers, ... We tried a lot of different setups and finally settled for odtphp/gotenberg to have the PDF output "pixel perfect". Another limitation was that we needed about 50,000 PDFs per day for which we run parallel queues to the PDF converters.

Technical informations

Why do my variables sometimes not get filled in?

Because LibreOffice adds metadata to text that you change. E.g. when you have something as follows in your ODT file:

And you make a small change to the previous text it may very well end up as:

where you don't see the "text:span" part visually, but it is there. And since odtphp plainly matches variables in an ODT file, the variable name will not match anymore and will not be replaced.

How to get around that: When you change variable texts, select the variable text (including the begin and end delimiters), copy it, and then use "Paste special/Paste unformatted text" to copy the text in the same place without any invisible metadata.

Variables vs Custom Properties

ODT files support two different ways to insert dynamic content: variables and custom properties.

Variables

Variables are an ODTPhp feature that works by replacing text anchors (like {variable_name}) with new content:

Key points about variables:

Custom Properties

Custom properties are an official ODT feature for storing metadata about the document:

Key points about custom properties:

When to use which:

Why does "Catégorie 1" sometimes appear as "Catégorie 1" in the output?

Usually this is a double-encoding problem. When UTF-8 text is encoded again as UTF-8, special characters like 'é' can appear as 'é'. This typically
happens when the text is already in UTF-8 but gets encoded again.

While setting variables you can specify the encoding as needed, e.g. as:

The default charset has changed?

One of the "major" changes I made is to put UTF-8 as the default charset when setting variables. Before the default was ISO-8859-1, but UTF-8 currently makes more sense to me.

I always recommend using UTF-8 internally within the application and handling encoding/decoding at the boundaries.

How do I upgrade from v1/v2 to v3?

While it is a breaking change, as long as you only use odtphp and don't use any of its internals you should be fine by just upgrading the odtphp library to v3.

If you inherit from Odf or you use some internal things in the odtphp library, then all bets are off.

History

The odtphp project was initially started by Julien Pauli, Olivier Booklage, Vincent Brouté and published at http://www.odtphp.com (the website no longer exists).

As DXC Technology working for the Flemish government we started using the cybermonde/odtphp fork (source) in a couple of projects to fill in template ODT files with data, then transforming the filled-in ODT to PDF using gotenberg. We ran into a couple of problems with the cybermonde/odtphp library for which it was easier to just create my own fork, hence sboden/odtphp: we sometimes generate 50,000 forms daily, and cybermonde/odtphp would occasionally overwrite outputs when processing a lot of ODT files simultaneously (because of non-random random numbers).

Why do I try to keep this "corpse" alive? Simply because I found no replacement for it. The projects I work that use odtphp are now (= end 2024) on PHP 8.2 moving to PHP 8.3, and some pieces of the original odtphp library are starting to spew warnings. During my 2024 Christmas holidays I was writing some unit test cases for odtphp, and while testing the AI tool "Windsurf", I tried to have Windsurf automatically update odtphp to a newer PHP version, and sboden/odtphp v3 is the result of that (after some extra manual human changes).

While this fork sboden/odtphp is not officially supported, maintenance and bug fixes are provided on a best-effort basis. The sboden/odtphp library is actively used in production applications with planned lifecycles extending to at least 2030.

This software is not by DXC Technology, else it would have been called dxc/odtphp. This software is not by the Flemish government, else it would probably have been called vo/odtphp. I have always worked on odtphp during my personal time.

Version History

Disclaimer

This software is provided "as is" without warranty of any kind, either expressed or implied. The entire risk as to the quality and performance of the software is with you.

In no event will the authors, contributors, or licensors be liable for any damages, including but not limited to, direct, indirect, special, incidental, or consequential damages arising out of the use or inability to use this software, even if advised of the possibility of such damage.

By using this software, you acknowledge that you have read this disclaimer, understand it, and agree to be bound by its terms.

Links:


All versions of odtphp with dependencies

PHP Build Version
Package Version
Requires php Version >=8.1
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package sboden/odtphp contains the following files

Loading the files please wait ....