Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/belgattitude/pjbserver-tools
PHP JavaBridge server tools
https://github.com/belgattitude/pjbserver-tools
cli php-java-bridge soluble-japha
Last synced: 2 days ago
JSON representation
PHP JavaBridge server tools
- Host: GitHub
- URL: https://github.com/belgattitude/pjbserver-tools
- Owner: belgattitude
- License: mit
- Created: 2015-11-21T12:29:19.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2021-04-25T17:33:24.000Z (over 3 years ago)
- Last Synced: 2024-08-10T10:57:09.414Z (about 2 months ago)
- Topics: cli, php-java-bridge, soluble-japha
- Language: PHP
- Size: 2.15 MB
- Stars: 10
- Watchers: 4
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# pjbserver-tools
[](https://packagist.org/packages/belgattitude/pjbserver-tools)
[](https://packagist.org/packages/belgattitude/pjbserver-tools)
[](https://packagist.org/packages/belgattitude/pjbserver-tools)
[](https://travis-ci.org/belgattitude/pjbserver-tools)
[](https://codecov.io/gh/belgattitude/pjbserver-tools)
[](https://scrutinizer-ci.com/g/belgattitude/pjbserver-tools/?branch=master)
[](https://packagist.org/packages/belgattitude/pjbserver-tools)
[](https://packagist.org/packages/belgattitude/pjbserver-tools)
[](https://packagist.org/packages/belgattitude/pjbserver-tools)
The `pjbserver-tools` package currently provides an easy installable php java bridge standalone server.
See the [soluble/japha](https://github.com/belgattitude/soluble-japha) and [php-java-bridge](https://github.com/belgattitude/php-java-bridge)
projects to get more info about php/java integration.
> **Note** that the `pjbserver-tools` standalone server utility
> was made for easy composer installation when developing or testing.
>
> **For production, building a customized PHPJavaBridge server is
> really easy. Check the recommended [php/java/bridge installation notes](http://docs.soluble.io/soluble-japha/install_server/)**
## Use cases
The java bridge standalone server can be used as an alternative to a regular bridge installation
for php/java integration while keeping things simple for development, unit testing or small projects.
## Features
- Easy setup of a PHP Java bridge standalone server (*nix).
- Console commands to control the server (start/stop/restart/status).
- API library to customize the behaviour.
- Includes compiled [JavaBridge.jar](./resources/pjb713_standalone/JavaBridge.jar) 7.1.3 file.
## Requirements
- PHP 5.5+, 7.0 or HHVM >= 3.2.
- Linux/Unix *(Mac OSX 10.1+ reported working)*.
- Java 1.7+ (see [install instructions](./doc/install_java.md)).
## Installation
> **WARNING** The phpjavabridge server is not supposed to be run on a public facing server
> and its use should be limited to interactions on the same host/network with the php client.
> Do not run it as root neither as it exposes the JVM methods through the network that
> could be remotely exploited. Do not start it as root neither.
Depending on your needs you can use the pjserver-tools in two ways.
1. Option 1: Composer install
You can easily add the pjbserver-tools to your existing [composer](http://getcomposer.org/) project.
```console
$ composer require belgattitude/pjbserver-tools
```
It can also be added to your development dependencies (replace `require` by `require --dev` in the
previous command). Very helpful if you intend to test with Travis...
Test a command line.
```console
./vendor/bin/pjbserver-tools pjbserver:status ./vendor/belgattitude/pjbserver-tools/config/pjbserver.config.php.dist -vvv
```
2. Option 2: Console, clone the repo.
First create a path on your filesystem that will hold the server install.
```console
$ mkdir -p /my/path/pjbserver-tools
$ cd /my/path/pjbserver-tools
```
Clone the repository and use run [composer](http://getcomposer.org) update.
```console
$ git clone https://github.com/belgattitude/pjbserver-tools.git
$ cd pjbserver-tools
$ composer update
```
Test a command line
```
./bin/pjbserver-tools pjbserver:status ./config/pjbserver.config.php.dist -vvv
```
## Usage
### Command line
Command line depends on your install method (composer or clone/download).
- With composer the location of the binary is `./vendor/bin/pjbserver-tools` and the default
config is located in `./vendor/belgattitude/pjbserver-tools/config/pjbserver.config.php.dist`.
- With the clone method, binary is `./bin/pjbserver-tools` and default config is `./config/pjbserver.config.php.dist`.
*For clarity, the documentation of console commands is based on the clone method. Simply
replace your path whenever needed.*
You can use the commands
`pjbserver:start`, `pjbserver:stop`, `pjbserver:restart`, `pjbserver:status` followed
by the `pjbserver.config.php` file to control or query the server status.
```console
$ ./bin/pjbserver-tools pjbserver:start -vvv ./config/pjbserver.config.php.dist
$ ./bin/pjbserver-tools pjbserver:stop -vvv ./config/pjbserver.config.php.dist
$ ./bin/pjbserver-tools pjbserver:restart -vvv ./config/pjbserver.config.php.dist
$ ./bin/pjbserver-tools pjbserver:status -vvv ./config/pjbserver.config.php.dist
$ # for listing the java cli command issued :
$ ./bin/pjbserver-tools pjbserver:reveal ./config/pjbserver.config.php.dist
```
If you use the [./config/pjbserver.config.php.dist](./config/pjbserver.config.php.dist) config file, the server will start on port ***8089***.
Feel free to create a local copy of this file and adapt for your usage :
```console
$ cp ./config/pjbserver.config.php.dist /my/path/pjbserver.config.php
```
*Note that the -v, -vv, -vvv option in the command line allows to define the verbosity level of the scripts.*
### Controlling via the API
Command line is good, but API gives a little more control especially good when setting unit tests and CI.
Here's a little example:
```php
$tcp_port,
/**
* Location of log and pid files...
* Defaults is to put them in the project 'pjbserver-tools/var/...' directory
* which is fine for unit testing, but to prevent loosing those files
* set a safe directory (not /tmp as it might be cleared by the OS)
*/
//'log_file' => "/my/path/var/pjbserver-port${tcp_port}.log",
//'pid_file' => "/my/path/var/pjbserver-port${tcp_port}.pid",
// Optional but often more than useful
'classpaths' => [
'/my/path/*.jar',
'/another/path/mylib.jar'
],
// Standalone server tuning
// Number of threads for standalone server is 50, increase if needed
//'threads' => 50,
// Java binary
// change location if you like, for example
// /usr/lib/jvm/java-8-oracle/bin/java
'java_bin' => 'java',
/**
* Location of the JavaBridge.jar,
* Default is to use the default (included) one
* available in pjbserver-tools/resources/pjb713_standalone/JavaBridge.jar
*/
//'server_jar' => "/my/path/pjb713_standalone/JavaBridge.jar",
]);
$server = new StandaloneServer($config);
try {
$server->start();
} catch(\Exception $e) {
// Exception message
echo $e->getMessage();
// Server output logs
echo $server->getOutput();
die();
}
echo "Started: " . ($server->isStarted() ? 'yes' : 'no') . PHP_EOL;
echo "Running: " . ($server->isProcessRunning() ? 'yes' : 'no') . PHP_EOL;
echo "Pid : " . $server->getPid() . PHP_EOL;
// Stopping the server
$server->stop();
```
You can also inject any PSR-3 compatible logger to the `StandaloneServer`.
```php
// any PSR-3 compatible logger
$logger = new \Psr\Log\NullLogger();
$server = new StandaloneServer($config, $logger);
```
## Configuration
The dist config file [./config/pjbserver.config.php.dist](https://github.com/belgattitude/pjbserver-tools/blob/master/config/pjbserver.config.php.dist)
contains the default parameters used in console mode.
### Parameters
| Key | Type | Comment |
|----------------|--------|--------------------------------------------------|
| `port` | int | TCP port on which standalone server listen |
| `classpaths` | array | Java additional classpaths |
| `threads` | int | Server max number of threads |
| `java_bin` | string | Java binary executable (with or without path) |
| `server_jar` | string | Path to the JavaBridge.jar file |
| `log_file` | string | Path to the standalone server log file |
| `pid_file` | string | Path to the standalone pid file |
Some considerations:
- When choosing a `port`, ensure it's not available publicly (security).
- The default config set `log_file` and `pid_file` in the ./var directory, please
change the default location to your data directory.
- Avoid storing `log_file` and `pid_file` in the global temp directory '/tmp' as it might
be cleared by the OS at anytime.
### Classpath configuration
Whenever you need to add some java libraries, simply edit the configuration file and look for the
`classpaths` option and add the required jar files.
As an example:
```php
8089,
'classpaths' => [
'/my/path/autoload/mysql-connector.jar',
'/my/autoload_path/*.jar'
],
];
```
Don't forget to restart the standalone server to reflect the changes.
*Using wildcard* `/my/path/*.jar` *is possible but should be used with care. All matching files will be appended to classpath
by passing arguments in a shell exec. Limits exists...*
## Debugging
Some useful commands to watch, debug and eventually kill java standalone server process
### Getting the status (running/not running)
```console
$ ./bin/pjbserver-tools pjbserver:status -vvv ./config/pjbserver.config.php.dist
```
### Reveal the issued command
```console
$ ./bin/pjbserver-tools pjbserver:reveal -vvv ./config/pjbserver.config.php.dist
```
For example, the issued command the default config can be
```console
$ java -cp "/xxx/pjbserver-tools/resources/pjb713_standalone/JavaBridge.jar" -Dphp.java.bridge.daemon="false" -Dphp.java.bridge.threads=50 php.java.bridge.Standalone SERVLET:8089
```
### Process management
If for any reason the server cannot be stopped through the console, you can
lookup the process through the command line.
```console
$ # Searching by listening port
$ netstat -nlp | grep : # might require sudo if server started as root
$ # Searching by name
$ ps ax | grep JavaBridge.jar
$ # Searching by custom filter
$ pgrep -f "(.*)java(.*)JavaBridge.jar(.*)SERVLET:8089"
```
You can kill the process:
```
$ kill
```
## FAQ
### How to start automatically at boot
Check for "supervisord" on google, you'll find some recipes but the
preferred method is to deploy on Tomcat, see:
- [pjb-starter-springboot](https://github.com/belgattitude/pjb-starter-springboot/) to build you own production, self-container or deployable servlet or
- [php-java-bridge](https://github.com/belgattitude/php-java-bridge) project.
For alternatives to pjbserver-tools standalone.
## Coding standards
* [PSR 4 Autoloader](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md)
* [PSR 3 Logger interface](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md)
* [PSR 2 Coding Style Guide](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
* [PSR 1 Coding Standards](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md)