Easy starter to package a PHPJavaBridge server with custom dependencies in minutes.
While both the recent PHPJavaBridge server fork and this starter can be easily customized (in pretty much the same way), the latter features a standalone
.jar
build (embedded Tomcat 8.5 ) in addition to the standard.war
file and offer support for Spring boot for additional customizations. Those features comes with a cost in term of dependencies size (overhead of 11Mb comparing to barebone phpjavabridge) although no speed differences have been measured between both bundles.Be aware that this starter does not register the PHPCGIServlet by default and thus does not require a php-cgi installation in order to run (a common issue when installing the bridge). While most use cases does not requires it (Java->PHP), its activation is possible, see the FAQ.
- Java JDK 8, see docs/install_java.md
- Optionally Tomcat when not using standalone.
- Recent soluble PHPJavaBridge servlet registered.
- Compatible with the soluble-japha client.
- Based on spring boot with thymeleaf architecture.
- Gradle init-scripts examples for managing dependencies (jasperreports, poi, corenlp...).
- By default, does not require a
php-cgi
present (see the FAQ about PHPCGIServlet) - Dashboard landing page with json monitoring address.
- Build easily manageable from the command line (gradle and init-scripts).
- Provides a standalone
.jar
with an embedded tomcat (in addition to standard .war file).
Packaging and deploying a customized PHPJavaBridge server could be done in 3 steps:
-
Clone the project (or download and unzip the release archive)
$ git clone https://github.com/belgattitude/pjb-starter-springboot $ cd pjb-starter-springboot
-
Build the
.war
and.jar
filesExample of build with jasperreports and mysql jdbc connector. See the '-I' parameter in the command below. Refer to the init-scripts doc for other recipes.
$ ./gradlew build -I init-scripts/init.jasperreports.gradle -I init-scripts/init.mysql.gradle
Your builded files are saved in the
build/libs
, typels -la build/libs
to list them. -
Run standalone server
.jar
from the command line (optional, skip to 4 for tomcat deployment)$ java -jar ./build/libs/JavaBridgeStandalone.jar -Dserver_port=8090
Open your browser and check the landing page located at http://localhost:8090.
-
Alternatively deploy the
.war
on Tomcat (when not using standalone)Tomcat deployment is the preferred way over the standalone
.jar
mode for production. While the standalone is also running under tomcat (embedded tomcat 8.5 ), the Tomcat provided with your OS is a better choice regarding standard location of log files as well as boot startup integration.cp ./build/libs/JavaBridgeTemplate.war /var/lib/tomcat8/webapps/MyJavaBridge.war
Wait few seconds and point your browser to http://localhost:8080/MyJavaBridge.
Note that the
/MyJavaBridge/
URI corresponds to the war filename as copied in the webapps folder... feel free to adapt to your own needs. To re-deploy (deploy an updated version), simply copy the new.war
file, Tomcat will apply the changes automatically.
Don't forget to read the full documentation below, especially security considerations when exposing the PHPJavaBridge server to the outside world, some common issues with memory in the FAQ and read the soluble-japha doc for PHP/Java interactions.
Clone the project
$ git clone https://github.com/belgattitude/pjb-starter-springboot/
If you intend contribute or want to keep a track of changes, consider making your own fork first and refer it in the clone command instead of the main project.
Call the build
gradle task:
$ ./gradlew build
And check the build\libs
directory for the following files:
File | Description | Approx. size |
---|---|---|
JavaBridgeStandalone.jar |
Standalone server with an embedded Tomcat 8.5 . | /- 32Mb |
JavaBridgeTemplate.war |
War file, ready to drop into Tomcat webapps folder. | /- 12Mb |
Approx. size is given as a reference of the current default build.
The following example use bootRun
task to run the server. Choose Tomcat deployment or the
standalone mode for production.
$ ./gradlew bootRun
# or specify the port with gradle bootRun -Dserver.port=8090
And point your browser to http://localhost:8090.
Create a php project in a directory of your choice and install the soluble-japha client.
$ composer require soluble/japha
Set the connection to the running phpjavabridge server (port 8090 by default)
<?php
require 'vendor/autoload.php'; // for composer autoload
use Soluble\Japha\Bridge\Adapter as BridgeAdapter;
$ba = new BridgeAdapter([
'driver' => 'Pjb62',
'servlet_address' => 'localhost:8090/servlet.phpjavabridge'
]);
$system = $ba->javaClass('java.lang.System');
echo $system->getProperties()->get('java.vm_name');
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. In its default configuration the pjb⁻starter example does not provide any security mechanisms so any url with an extension of '*.phpjavabridge' could be remotely exploited.
To run simply
$ java -jar ./build/libs/JavaBridgeStandalone.jar -Dserver_port=8090
And point your browser to http://localhost:8090 to check.
Copy to the Tomcat webapp directory to deploy:
cp ./build/libs/JavaBridgeTemplate.war /var/lib/tomcat8/webapps/MyJavaBridge.war
wait few seconds and point your browser to http://localhost:8080/MyJavaBridge.
Note that the port may vary and the URI (or server context) is taken from the deployed filename. In this example: 'MyJavaBridge', feel free to change.
Repeat operation whenever you need to (re-)deploy.
Have a look a those files:
File | Desc |
---|---|
build.gradle | Customize your dependencies here (jasper...), version,... |
main/resources/application.yml | Various spring-boot application settings |
main/java/io/soluble/pssb/Application.java | Where servlets, filters... are registered. |
settings.gradle | Customize the root project name |
Modify for your usage and rebuild with grade bootRun
to check.
Note that the welcome page is handled by the main/java/io/soluble/pssb/mvc/IndexController.java with dependencies in the 'templates' and 'static' subdir in resources folder.
With the self-contained tomcat
> export JAVA_OPTS=-Xmx512m -XX:MaxPermSize=128M
If deployed on Tomcat
$ vi /etc/default/tomcat8
Look for the Xmx default at 128m and increase
JAVA_OPTS="-Djava.awt.headless=true -Xmx512m -XX: UseConcMarkSweepGC"
and restart
sudo service tomcat8 restart
The pjb-starter-springboot
includes a very basic PingController, you can call it on http://localhost:8090/ping.json, you should see
{
"date": 1484919571831,
"success": true,
"message": "PHPJavaBridge running"
}
You can either add your dependencies directly in the
build.gradle
file or use the init-script method. The latter is preferred if you prefer to keep thebuild.gradle
file intact.
-
Preferred method: Use the init-script method.
Have a look to the init-script method documentation.
-
Alternative method: Modify the
build.gradle
file: Just open the build.gradle and check the runtime (or compile) sections.dependencies { // Spring-boot stuffs providedRuntime "org.springframework.boot:spring-boot-starter-tomcat:${spring_boot_version}" testCompile "org.springframework.boot:spring-boot-starter-test:${spring_boot_version}" compile "org.springframework.boot:spring-boot-starter-web:${spring_boot_version}" compile ("org.springframework.boot:spring-boot-starter-thymeleaf:${spring_boot_version}") { exclude group: 'org.codehaus.groovy', module: 'groovy' } compile "org.springframework.boot:spring-boot-devtools:${spring_boot_version}" // Useful for dev (auto disabled on prod) compile "com.google.code.gson:gson:2.8.0" // Deps for the ping address // PHPJavaBridge compile("io.soluble.pjb:php-java-bridge:${pjb_version}") { // In sprint-boot, you can exclude javax.servlet and log4j exclude group: 'javax.servlet', module: 'javax.servlet-api' } /** ####################################################### * Here you can add runtime dependencies to the project * ------------------------------------------------------- * Those dependencies will be included available in the * builded war file. Alternatively you may register deps * through the 'init-script' method. * (check 'init-scripts/README.md' folder for insights) * ####################################################### */ // example: mysql jdbc connector /*runtime "mysql:mysql-connector-java:6. "*/ }
Have a look to maven repo to quickly find your deps
For PHP users, gradle might not sound familiar. In the context of adding libraries, you can consider it as a package manager like composer, npm... To add or define dependencies
simply edit the dependencies section of the build.gradle file. Generally in the 'runtime' subsection.
If you use the Tomcat deployment it should start by default. With the self-container tomcat, ask google for "supervisord spring boot".
BootRun task is really useful when developping and allows hot reloading when you customize css, html pages...
$ ./gradlew bootRun
# or specify the port with gradle bootRun -Dserver.port=8090
And point your browser to http://localhost:8090.
By default this template does not enable Java->PHP
by default. So if you intend to
use PHP from Java, you must add to the Application.java the following methods:
public class Application extends SpringBootServletInitializer {
/// Normal initialization sequence
/**
* Register the php.java.servlet.fastcgi.FastCGIServlet
* <p>
* It replaces the following section found in the original web.xml config:
* <p>
* <pre>
* {@code
* <servlet>
* <servlet-name>PhpCGIServlet</servlet-name>
* <servlet-class>php.java.servlet.fastcgi.FastCGIServlet</servlet-class>
* <load-on-startup>0</load-on-startup>
* </servlet>
* <servlet-mapping>
* <servlet-name>PhpCGIServlet</servlet-name>
* <url-pattern>*.php</url-pattern>
* </servlet-mapping>
* }
* </pre>
*/
@Bean
public ServletRegistrationBean phpCGIServletDispatcherRegistration() {
FastCGIServlet phpJavaServlet = new io.soluble.pjb.servlet.fastcgi.FastCGIServlet();
ServletRegistrationBean registration = new ServletRegistrationBean(
phpJavaServlet);
registration.addUrlMappings("*.php");
registration.setLoadOnStartup(0);
return registration;
}
/**
* Register the php.java.servlet.PhpCGIFilter
* <p>
* This filter extend the servlet spec 2.2 "url-pattern"
* to handle PHP PATH_INFO: *.php/something?what=that.
* Remove it, if you don't need this feature.
* <p>
* <pre>
* {@code
* <filter>
* <filter-name>PhpCGIFilter</filter-name>
* <filter-class>php.java.servlet.PhpCGIFilter</filter-class>
* </filter>
* <filter-mapping>
* <filter-name>PhpCGIFilter</filter-name>
* <url-pattern>/*</url-pattern>
* </filter-mapping>
* }
* </pre>
*/
@Bean
public FilterRegistrationBean someFilterRegistration() {
FilterRegistrationBean registration = new FilterRegistrationBean();
registration.setFilter(new io.soluble.pjb.servlet.PhpCGIFilter());
registration.addUrlPatterns("/*");
//registration.addInitParameter("paramName", "paramValue");
registration.setName("PhpCGIFilter");
registration.setOrder(1);
return registration;
}
}
And ensure you have the php-cgi installed and available on your system.
An example page main/webapp/index.php page is already provided as a starting point.... Try http://localhost:8090/index.php
Debugging can be enabled with the standalone server:
$ java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n \
-jar ./build/libs/JavaBridgeStandalone.jar
- Modernized
JavaBridgeTemplate.jar
example- JDK8, spring boot, thymeleaf.
- JavaBridgeServlet registered
PHP->Java
- (from php use the soluble-japha client. - PhpCGIServlet registration example
Java->PHP
(disabled by default, doc exists) - Original PhpJavaBridge config properties in the original web.xml (like location of the php-cgi executable...)
- Service landing page
- Refactored welcome landing page.
- Ping address for monitoring.
- Display server/java infos
- Documentation
- How to customize (WIP)
- Basic security recipes, incl. bind on localhost
- Document how to add local jar deps (out of maven)
Feel free to fork and submit pull requests.
- Initially made with love by Sébastien Vanvelthem.
- [Contribute and appears here]