Migrating

From Version 2.46 to >=2.47 (Namespaces)

In version 2.47 we finally introduce namespaces into the code base which results in a complete new class structure and class names.

All classes were renamed and we added a backwards compatiblity layer with the use of class aliases to support the old class names. So there's no real need to refactor but it's simply a cosmetic change and a matter of style. All our demos and documentation will use the namespaced version in the future.

The new root namespace for SetaPDF (v2) is: setasign\SetaPDF2

All classes of the SetaPDF-Core component are located in: setasign\SetaPDF2\Core

You can find the new class names by following the class alias definition in your IDE or simply search for the old class name in the manual.

We intensively tested the namespaced version with projects, our own test-suite and by using the old class names internally during the refactor process. An upgrade is possible without touching any code.

Anyhow, we found very rare and special situations which you need to pay attention on and which we documented in the following paragraphs.

If you encounter any problem or question, do not hesitate to contact us at support@setasign.com.

Make sure that instanceof and not get_class() is used

If you check the type of an object from SetaPDF with the get_class() function you have to switch to an instanceof statement. This can happen but is generally a bad practice and should be optimized anyway.

E.g. following if-statement:

PHP
if (get_class($action) === 'SetaPDF_Core_Document_Action_GoTo') {
    // ...   
}

shall be changed to:

PHP
if ($action instanceof \SetaPDF_Core_Document_Action_GoTo) {
    // ...
}

Or with the new class name:

PHP
if ($action instanceof \setasign\SetaPDF2\Core\Document\Action\GoToAction) {
    // ...
}

Update allowed_classes in unserialize() calls

If you use serialized objects from SetaPDF in any way and you make use of the allowed_classes option in the unserialize() call, you have to add the new class names.

Update Individual Autoloader

If you use your own autoload function instead of the autoloader from composer or the default Autoload.php file, you have to make sure, that both PSR-0 and PSR-4 logics are handled. Both share the same root folder.

PSR-0:

PHP
    'SetaPDF_' => 'library/SetaPDF'

PSR-4:

PHP
    'setasign\\SetaPDF2\\' => 'library/SetaPDF'

Behavior of "Autoloader optimization" in Composer

Composer allows you to optimize the autoloader logic by creating and saving class maps which avoid additional checks in the filesystem.

As the optimization is only available for classes and not class aliases, it will only take effect for the classes in the namespace setasign\SetaPDF2\.

For Optimization Level 1 the autoloader will fallback to the PSR-0 implementation if the old class names are used.

For Optimization Level 2 we additionally register our Autoload.php file in the autoload configuration as an additional fallback.

In version 2.47 a full authoritative class map is not possible. The code will work but a full optimization is not possible.
In version > 2.47 all internal class names were updated to the new namespace. By using these versions and after a complete refactor on your end, it is possible to benefit from authoritative class maps again.