soluble/japha

Soluble PHP Java bridge integration


README

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 http://docs.soluble.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.

  • 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 ^2.0 requires PHP 7.1 PHP Version

Important. There's NO API BC-BREAK between v0.13, v1.x and v2.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 PHP Version and works with HHVM.
  • Version ^0.13 requires PHP 5.5 PHP Version and works with HHVM.

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.

Future ideas

Short term

  • Achieve at least 80% of unit testing for legacy code.
  • Remove obsolete code from PJB62 driver (will also increase coverage)
  • Work on performance

Experiments

  • Improve proxy and use of ProxyManager
  • Drop XML protocol in favour of protocol buffers or GRPC
  • Create a JSR-223 php extension in Go, like this experiment

Credits

Special mention

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

PHPStorm

Coding standards and interop