Java PHP Serializer

Latest release:

A Java library for serializing objects as PHP serialization format.

The library fully implements the PHP serialization format specification, which includes:

• Scalar values
• Objects
• Serializable (custom serializable objects)
• Object and variable references

The API documentation is available on GitHub Pages more convenient viewing in browser.

A word of notice

This library does not provide any mechanism for creating a communication channel between Java and PHP. For such purpose, consider using Soluble Java.

Use case

One of the easier way to exchange data between Java and PHP consists in serializing the value to a data-interchanging format, such as JSON or XML, send it through a communication channel and finally deserialize it back to the original form on the PHP side. The problem with this approach is that the cost of deserializing complex objects in PHP is very high.

Most of the serialization libraries in PHP use reflection for re-hydrating objects, and it becomes an issue when you have to deserialize large structures with hundreds of objects. Fortunately, PHP's native serialization is fast and the unserialize() function can handle such cases in a few milliseconds.

This library implements the full format specification through a friendly API that encapsulates the complexity of the serialization process.

Installation

Maven

The PHP Serializer is available in the Maven Central repository. Any Maven based project can use it directly by adding the appropriate entries to the dependencies section of its pom.xml file:

<dependencies>
  <dependency>
    <groupId>com.marcospassos</groupId>
    <artifactId>phpserializer</artifactId>
    <version>0.8.0</version>
  </dependency>
</dependencies>

Binaries

Packaged JARs can be downloaded directly from the releases page and extracted using tar or unzip.

Usage

How to serialize data

The first step to serialize a Java object into a PHP serialization format string is to create a Serializer instance according to your application domain model. The library ships a builder that help us with this task:

Serializer serializer = new SerializerBuilder()

  // Adds a custom exclusion strategy to determine which field
  // should be serialized or not (default: no exclusion)
  .addExclusionStrategy(new MyCustomExclusionStrategy())
  
  // Sets the naming strategy to convert the name of classes
  // and fields from Java to PHP (default: PsrNamingStrategy)
  .setNamingStrategy(new MyCustomNamingStrategy())
  
  // Registers all builtin adapters, using UTF-8 for encoding strings 
  // (default: all built-in adapters, UTF-8 charset)
  .registerBuiltinAdapters()
  
  // Sets ISO-8859-1 as the default charset
  //
  // Notice that setCharset() register a new adapter configured with the 
  // specified charset. Calling setCharset() prior to registerBuiltinAdapters()
  // will have no effect as the previous configuration will get overriden
  // by the default adapter which encodes strings in UTF-8. 
  .setCharset(Charset.forName("ISO-8859-1"))
  
  // Register a custom type adapter
  .registerAdapter(CustomObject.class, new CustomObjectAdapter())
  
  // Creates the serialized based on the given configuration
  .build();

Now you have a Serializer instance configured according to your application domain model. To serialize a value, just invoke serialize(Object object) on the serializer instance:

List list = new ArrayList();
list.add("A string");
list.add(12345);
list.add(true);

// Outputs: a:3:{i:0;s:8:"A string";i:1;i:12345;i:2;b:1;}
System.out.println(serializer.serialize(list));

Naming strategies

A naming strategy allows you to translate the name of classes and fields according to the target domain model. The library ships with a built-in adapter that converts Java packages to PHP namespaces in accordance with PSR-1 rules. If the PSR strategy does not fit your needs you can easily implement a custom naming strategy. Takes as reference the following strategy that appends an underscore to all private fields:

public class UnderscoreNamingStrategy implements NamingStrategy
{
    public String getClassName(Class type)
    {
        return type.getName();
    }

    public String getFieldName(Field field)
    {
        if (Modifier.isPrivate(field.getModifiers())) {
            return "_" + field.getName();
        }

        return field.getName();
    }
}

Type Adapters

A type adapter provides the serializer the logic for how to encode a specific type. The following example shows how to create a custom type adapter to serialize Enums as string using the name of the enum constant:

public class EnumTypeAdapter implements TypeAdapter<Enum>
{
    public void write(Enum value, Writer writer, Context context)
    {
        writer.writeString(value.name());
    }
}

Notice that circular references are handled as per case basis, once it is not always the desirable. For instance, you may not want to serialize lists as objects references, as array is probably the most appropriate corresponding type in PHP. The following example shows how to handle such cases:

public class MyCustomAdapter implements TypeAdapter<CustomObject>
{
    @Override
    public void write(CustomObject object, Writer writer, Context context)
    {
        int reference = context.getReference(object);

        if (reference > 0) {
            writer.writeObjectReference(reference);

            return;
        }

        context.setReference(reference, object);

        // Custom serialization logic
    }
}

Change log

Please see CHANGELOG for more information what has changed recently.

Contributing

Contributions to the package are always welcome!

• Report any bugs or issues you find on the issue tracker.
• You can grab the source code at the package's Git repository.

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Marcos Passos

• All Contributors

License

All contents of this package are licensed under the MIT license.

Copyright (c) 2018 Marcos Passos <[email protected]>

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.