Home

Awesome

soluble-japha

PHP Version PHP Version PHP Version Build Status codecov Scrutinizer Code Quality Latest Stable Version Total Downloads License

In short soluble-japha allows to write Java code in PHP and interact with the JVM ecosystem.

Read the doc on https://belgattitude.github.io/soluble-japha website for complete information

As meaningless examples:

<?php
// Some standard JVM classes
$hashMap = $ba->java('java.util.HashMap', [
        'message' => 'Hello world',
        'value'   => $ba->java('java.math.BigInteger', PHP_INT_MAX)
]);
$hashMap->put('message', '你好，世界');
echo $hashMap->get('message');

<?php

use Soluble\Japha\Bridge\Exception;

// An imaginary java library class (i.e. NLP, Android, Jasper, Tensorflow,
// enterprise stuff, esoteric java lib/driver or your own Java class...)
try {
    $javaLib = $ba->java('an.imaginary.JavaLibraryClass', 'param1', 'param2');

    $results = $javaLib->aMethodOnJavaLibExecutedOnTheJVM(
                            // Method parameters
                            $hashMap->get('message'),
                            $ba->java('java.io.BufferedReader',
                                 $ba->java('java.io.FileReader', __FILE__)
                            ),
                            $ba->javaClass('java.util.TimeZone')->SHORT
                        );

    foreach ($results as $key => $values) {
        echo "$key: " . $values[0] . PHP_EOL;
    }
} catch (Exception\ClassNotFoundException $e) {
    echo $e->getMessage();
} catch (Exception\JavaException $e) {
    echo $e->getMessage() . ' [' . $e->getJavaClassName() . ']';
    echo $e->getStackTrace();
}

And if you're wondering what's the $ba object, it's a connection to the java bridge server:

<?php

use Soluble\Japha\Bridge\Adapter as BridgeAdapter;
use Soluble\Japha\Bridge\Exception as BridgeException;

$options = [
    'servlet_address' => 'localhost:8080/MyJavaBridge/servlet.phpjavabridge'
];

try {
    $ba = new BridgeAdapter($options);
} catch (BridgeException\ConnectionException $e) {
    // Server is not reachable
    echo $e->getMessage();
}

Use cases

Expand the PHP horizons to the Java ecosystem, especially whenever you want to take advantage of

The freedom allowed by soluble-japha is not fit for every scenarios. Be sure to read the considerations and performance sections to learn more.

Features

soluble-japha provides a PHP client to interact with the Java Virtual Machine.

For user of previous versions, soluble-japha client replaces the original/legacy PHPJavaBridge Java.inc implementation and has been completely refactored to fit modern practices and PHP7. See the differences here and the legacy compatibility layer if needed.

Requirements

Important. There's NO API BC-BREAK between v0.13, v1.x, v2.x and v3.x so you should be able to upgrade safely between releases. The choice to increment version numbers to drop support for older php versions was made to avoid any confusion with multiple php installs.

If you're looking for compatibility with older PHP versions, note that:

Documentation

Installation

Installation in your PHP project (client)

$ composer require soluble/japha

Considerations

In short, the bridge shines whenever you need to use directly a Java library within a reasonable number of method calls. Otherwise implement REST or RPC approaches for first-class system integrations.

The soluble-japha bridge can be seen as a function oriented solution in comparison to resource oriented ones (i.e. REST,...). From REST or even RPC-based solutions (XMLRPC, JsonRPC or gRPC), the bridge skips the need to write a service layer on the Java side and allows a more programmatic approach to PHP developers.

Depending on usage, the benefits of freedom offered by the bridge can become a limitation in term of performance. Keep in mind that the bridge is sensitive to the number of objects and method calls (named roundtrips) and if few hundreds of methods calls are often insignificant (a roundtrip is generally less than 0.1ms) going further its target scenarios can be disappointing. In those case, traditional approaches like REST should be considered and applied instead.

That said, the bridge is a good, reliable and sometimes preferable alternative over REST for scenarios where a reasonable number of methods calls is intended.

Be sure to read the

Support

Please fill any issues on the offical tracker. If you like to contribute, see the contribution guidelines. All P/R are warmly welcomed.

Credits

Special mention

Grateful thanks to JetBrains for granting an opensource license of PHPStorm and Idea. Really recommend !!!

PHPStorm

Coding standards and interop