README.md

soluble-japha

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

• some compelling libraries (Jasperreports, CoreNLP, FlyingSaucer, Jsoup...)
• benefit from JVM performances (Deeplearning4J...) or wrappers (TensorFlow Java Api...).
• when a pure-PHP alternative does not exists (Android, driver, closed api, enterprise...)
• or simply for the fun of it.

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.

• Write Java code from PHP (in a similar way from equivalent java code).
• Keep programmatic code control from the PHP side (function oriented vs REST).
• Java execution on the JVM ensuring compatibility and efficiency (proxied objects).
• No need to write a service layer prior to usage (the Java object is the contract).
• Fast network based communication between runtimes, no JVM startup effort.
• Solid foundation to create, develop or publish PHP wrappers over java libs.

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

• Version ^3.0 requires PHP 8.0
• Version ^2.0 requires PHP 7.1

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:

• Version ^1.0 requires PHP 5.6 and works with HHVM.
• Version ^0.13 requires PHP 5.5 and works with HHVM.

Documentation

• Go to https://belgattitude.github.io/soluble-japha

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

• http://docs.soluble.io/soluble-japha/bridge_how_it_works/
• http://docs.soluble.io/soluble-japha/bridge_benchmarks/

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

• This code is principally developed and maintained by Sébastien Vanvelthem.
• Special thanks to all of these awesome contributors
• This project is based on the Java.inc work made by the PHPJavaBridge developers.

Special mention

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

Coding standards and interop

• PSR 4 Autoloader
• PSR 3 Logger interface
• PSR 2 Coding Style Guide
• PSR 1 Coding Standards