{"id":15706127,"url":"https://github.com/belgattitude/pjb-starter-springboot","last_synced_at":"2025-05-12T18:46:34.114Z","repository":{"id":71987370,"uuid":"82047065","full_name":"belgattitude/pjb-starter-springboot","owner":"belgattitude","description":"Easy starter to build a PHPJavaBridge server with custom dependencies and spring-boot","archived":false,"fork":false,"pushed_at":"2019-05-27T17:04:07.000Z","size":886,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-18T03:37:04.777Z","etag":null,"topics":["php-java-bridge","phpjavabridge","server","skeleton","soluble-japha","spring-boot","standalone-server","starter"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/belgattitude.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-15T10:09:27.000Z","updated_at":"2022-12-21T22:52:19.000Z","dependencies_parsed_at":"2023-03-19T11:08:40.707Z","dependency_job_id":null,"html_url":"https://github.com/belgattitude/pjb-starter-springboot","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/belgattitude%2Fpjb-starter-springboot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/belgattitude%2Fpjb-starter-springboot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/belgattitude%2Fpjb-starter-springboot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/belgattitude%2Fpjb-starter-springboot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/belgattitude","download_url":"https://codeload.github.com/belgattitude/pjb-starter-springboot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229573266,"owners_count":18094714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["php-java-bridge","phpjavabridge","server","skeleton","soluble-japha","spring-boot","standalone-server","starter"],"created_at":"2024-10-03T20:21:38.287Z","updated_at":"2024-12-13T17:23:32.871Z","avatar_url":"https://github.com/belgattitude.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/belgattitude/pjb-starter-springboot.svg?branch=master)](https://travis-ci.org/belgattitude/pjb-starter-springboot)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nEasy starter to package a [PHPJavaBridge](https://github.com/belgattitude/php-java-bridge) server \nwith custom dependencies in minutes.    \n\n![](./docs/images/browser-home.png \"Landing page screenshot\")\n\n\u003e While both the recent [PHPJavaBridge server](https://github.com/belgattitude/php-java-bridge) fork and \n\u003e this starter can be easily customized (in pretty much the same way), the latter features a \n\u003e standalone `.jar` build (embedded Tomcat 8.5+) in addition to the standard `.war` file and\n\u003e offer support for [Spring boot](https://projects.spring.io/spring-boot/) for additional customizations.\n\u003e Those features comes with a cost in term of dependencies size (overhead of 11Mb comparing to barebone phpjavabridge) although no\n\u003e speed differences have been measured between both bundles. \n\u003e\n\u003e 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\n\u003e when installing the bridge). While most use cases does not requires it (Java-\u003ePHP), its activation is possible, see the FAQ.     \n    \n## Requirements\n\n- Java JDK 8, see [docs/install_java.md](./docs/install_java.md)\n- Optionally [Tomcat](./docs/install_tomcat.md) when not using standalone.\n\n## Features\n\n- [x] Recent soluble [PHPJavaBridge](https://github.com/belgattitude/php-java-bridge) servlet registered.\n- [x] Compatible with the [soluble-japha](https://github.com/belgattitude/soluble-japha) client.\n- [x] Based on [spring boot](https://projects.spring.io/spring-boot/) with thymeleaf architecture. \n- [x] Gradle [init-scripts](https://github.com/belgattitude/pjb-starter-springboot/blob/master/init-scripts/README.md) examples for managing dependencies (jasperreports, poi, corenlp...). \n- [x] By default, does not require a `php-cgi` present (see the FAQ about PHPCGIServlet)\n- [x] Dashboard landing page with json monitoring address.  \n- [x] Build easily manageable from the command line (gradle and init-scripts).\n- [x] Provides a standalone `.jar` with an embedded tomcat (in addition to standard .war file).\n\n## Quick start\n\nPackaging and deploying a customized PHPJavaBridge server could be done in 3 steps:\n    \n1. Clone the project *(or download and unzip the [release](https://github.com/belgattitude/pjb-starter-springboot/releases) archive)*\n\n   ```shell\n   $ git clone https://github.com/belgattitude/pjb-starter-springboot\n   $ cd pjb-starter-springboot\n   ```\n        \n2. Build the `.war` and `.jar` files \n    \n   Example of build with jasperreports and mysql jdbc connector. See the '-I' parameter in the command below.\n   Refer to the [init-scripts](https://github.com/belgattitude/pjb-starter-springboot/blob/master/init-scripts/README.md)\n   doc for other recipes. \n    \n   ```shell        \n   $ ./gradlew build -I init-scripts/init.jasperreports.gradle -I init-scripts/init.mysql.gradle\n   ```\n\n   Your builded files are saved in the `build/libs`, type `ls -la build/libs` to list them. \n    \n3. Run standalone server `.jar` from the command line (optional, skip to 4 for tomcat deployment)\n\n   ```shell\n   $ java -jar ./build/libs/JavaBridgeStandalone.jar -Dserver_port=8090\n   ```\n\n   Open your browser and check the landing page located at [http://localhost:8090](http://localhost:8090).\n    \n4. Alternatively deploy the `.war` on Tomcat (when not using standalone)\n    \n   \u003e Tomcat deployment is the preferred way over the standalone `.jar` mode for production. While the standalone\n   \u003e is also running under tomcat (embedded tomcat 8.5+), the Tomcat provided with your OS is a better choice\n   \u003e regarding standard location of log files as well as boot startup integration.   \n      \n   ```shell\n   cp ./build/libs/JavaBridgeTemplate.war /var/lib/tomcat8/webapps/MyJavaBridge.war\n   ```        \n    \n   Wait few seconds and point your browser to [http://localhost:8080/MyJavaBridge](http://localhost:8080/MyJavaBridge).\n          \n   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\n   (deploy an updated version), simply copy the new `.war` file, Tomcat will apply the changes automatically. \n    \n\nDon't forget to read the full documentation below, especially **security considerations** when exposing the PHPJavaBridge server\nto the outside world, some common issues with memory in the FAQ and read the [soluble-japha](https://github.com/belgattitude/soluble-japha) doc\nfor PHP/Java interactions. \n         \n## Documentation\n\n### 1. Get the project\n\nClone the project \n \n```shell\n$ git clone https://github.com/belgattitude/pjb-starter-springboot/ \n```\n\n\u003e If you intend contribute or want to keep a track of changes, consider making your [own fork](https://guides.github.com/activities/forking/) first and\n\u003e refer it in the clone command instead of the main project.  \n\n\n### 2. Build\n\nCall the `build` gradle task: \n\n```shell \n$ ./gradlew build \n```\n\nAnd check the `build\\libs` directory for the following files:\n\n| File          | Description   | Approx. size |\n| ------------- | ------------- | ------------ |\n| `JavaBridgeStandalone.jar`  | Standalone server with an embedded Tomcat 8.5+. | +/- 32Mb |\n| `JavaBridgeTemplate.war`    | War file, ready to drop into Tomcat webapps folder. | +/- 12Mb |\n\n\u003e Approx. size is given as a reference of the current default build. \n\n### 3. Run the PHPJavaBridge server.\n \nThe following example use `bootRun` task to run the server. Choose Tomcat deployment or the\nstandalone mode for production.\n\n```shell\n$ ./gradlew bootRun \n# or specify the port with gradle bootRun -Dserver.port=8090\n```\n\nAnd point your browser to [http://localhost:8090](http://localhost:8090).\n\n\n### 4. Connect from PHP\n\nCreate a php project in a directory of your choice and install the [soluble-japha](https://github.com/belgattitude/soluble-japha) client.\n\n```shell\n$ composer require soluble/japha\n```\n\nSet the connection to the running phpjavabridge server (port 8090 by default)\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php'; // for composer autoload\n\nuse Soluble\\Japha\\Bridge\\Adapter as BridgeAdapter;\n\n$ba = new BridgeAdapter([\n    'driver' =\u003e 'Pjb62', \n    'servlet_address' =\u003e 'localhost:8090/servlet.phpjavabridge'\n]);\n\n$system = $ba-\u003ejavaClass('java.lang.System');\necho $system-\u003egetProperties()-\u003eget('java.vm_name');\n\n```\n\n### 5. How to distribute, run or deploy\n\n\u003e **WARNING** The phpjavabridge server is not supposed to be run on a public facing server\n\u003e and its use should be limited to interactions on the same host/network with the php client.\n\u003e Do not run it as root neither as it exposes the JVM methods through the network. \n\u003e In its default configuration the pjb⁻starter example does not provide any security mechanisms\n\u003e so any url with an extension of '*.phpjavabridge' could be remotely exploited.      \n\n#### 5.1 Standalone (embedded tomcat8)\n\nTo run simply\n\n```shell\n$ java -jar ./build/libs/JavaBridgeStandalone.jar -Dserver_port=8090 \n```\nAnd point your browser to [http://localhost:8090](http://localhost:8090) to check.\n\n\n#### 5.2 Deploy on Tomcat 7/8\n\nCopy to the Tomcat webapp directory to deploy: \n\n```shell\ncp ./build/libs/JavaBridgeTemplate.war /var/lib/tomcat8/webapps/MyJavaBridge.war\n```\n\nwait few seconds and point your browser to [http://localhost:8080/MyJavaBridge](http://localhost:8080/MyJavaBridge).\n\n\u003e Note that the port may vary and the URI *(or server context)* is taken from the deployed filename. \n\u003e In this example: 'MyJavaBridge', feel free to change.  \n\nRepeat operation whenever you need to (re-)deploy.\n\n\n### 6. Advanced customizations\n\nHave a look a those files:\n\n| File  | Desc |\n| ------------- | ------------- |\n| [build.gradle](https://github.com/belgattitude/pjb-starter-springboot/blob/master/build.gradle)  |  Customize your dependencies here (jasper...), version,... |\n| [main/resources/application.yml](https://github.com/belgattitude/pjb-starter-springboot/blob/master/src/main/resources/application.yml)  | Various [spring-boot application settings](https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html)  |\n| [main/java/io/soluble/pssb/Application.java](https://github.com/belgattitude/pjb-starter-springboot/blob/master/src/main/java/io/soluble/pssb/Application.java)  | Where servlets, filters... are registered. |\n| [settings.gradle](https://github.com/belgattitude/pjb-starter-springboot/blob/master/settings.gradle) | Customize the root project name |\n\nModify for your usage and rebuild with `grade bootRun` to check.\n\n*Note that the welcome page is handled by the [main/java/io/soluble/pssb/mvc/IndexController.java](https://github.com/belgattitude/pjb-starter-springboot/blob/master/src/main/java/io/soluble/pssb/mvc/IndexController.java) with \ndependencies in the 'templates' and 'static' subdir in [resources](https://github.com/belgattitude/pjb-starter-springboot/tree/master/src/main/resources) folder.*  \n\n\n\n## Faq\n\n### OutOfMemory errors ?\n\nWith the self-contained tomcat\n\n```shell\n\u003e export JAVA_OPTS=-Xmx512m -XX:MaxPermSize=128M\n```\nIf deployed on Tomcat\n\n```shell\n$ vi /etc/default/tomcat8\n```\n\nLook for the Xmx default at 128m and increase \n\n```\nJAVA_OPTS=\"-Djava.awt.headless=true -Xmx512m -XX:+UseConcMarkSweepGC\"\n```\n\nand restart\n\n```shell\nsudo service tomcat8 restart\n```\n\n### How can I monitor that the bridge runs ?\n\nThe `pjb-starter-springboot` includes a very basic [PingController]((https://github.com/belgattitude/pjb-starter-springboot/blob/master/src/main/java/io/soluble/pssb/mvc/PingController.java)), you can call it on [http://localhost:8090/ping.json](http://localhost:8090/ping.json), you should see\n\n```json\n{\n    \"date\": 1484919571831,\n    \"success\": true,\n    \"message\": \"PHPJavaBridge running\"\n}\n```\n\n### How to add libraries to the builded war (jar) ?\n\n\u003e You can either add your dependencies directly in the `build.gradle` file \n\u003e or use the [init-script method](https://github.com/belgattitude/pjb-starter-springboot/tree/master/init-scripts).\n\u003e The latter is preferred if you prefer to keep the `build.gradle` file intact.\n \n\n1. Preferred method: Use the init-script method.\n\n    Have a look to the [init-script method](https://github.com/belgattitude/pjb-starter-springboot/tree/master/init-scripts) documentation. \n\n2. Alternative method: Modify the `build.gradle` file:\n    Just open the [build.gradle](./build.gradle) and\n    check the runtime (or compile) sections.\n    \n    ```gradle\n    dependencies {\n        // Spring-boot stuffs\n        providedRuntime \"org.springframework.boot:spring-boot-starter-tomcat:${spring_boot_version}\"\n        testCompile \"org.springframework.boot:spring-boot-starter-test:${spring_boot_version}\"\n        compile \"org.springframework.boot:spring-boot-starter-web:${spring_boot_version}\"\n        compile (\"org.springframework.boot:spring-boot-starter-thymeleaf:${spring_boot_version}\") {\n            exclude group: 'org.codehaus.groovy', module: 'groovy'\n        }\n        compile \"org.springframework.boot:spring-boot-devtools:${spring_boot_version}\"  // Useful for dev (auto disabled on prod)\n        compile \"com.google.code.gson:gson:2.8.0\"  // Deps for the ping address\n    \n        // PHPJavaBridge\n        compile(\"io.soluble.pjb:php-java-bridge:${pjb_version}\") {\n            // In sprint-boot, you can exclude javax.servlet and log4j\n            exclude group: 'javax.servlet', module: 'javax.servlet-api'\n        }\n    \n        /** #######################################################\n         *  Here you can add runtime dependencies to the project\n         *  -------------------------------------------------------\n         *  Those dependencies will be included available in the\n         *  builded war file. Alternatively you may register deps\n         *  through the 'init-script' method.\n         *  (check 'init-scripts/README.md' folder for insights)\n         *  #######################################################\n         */\n    \n        // example: mysql jdbc connector\n    \n        /*runtime \"mysql:mysql-connector-java:6.+\"*/\n    \n    }\n    ```\n    \n    Have a look to [maven repo](https://mvnrepository.com/) to quickly find your deps\n    \n    \u003e For PHP users, gradle might not sound familiar. In the context of adding libraries, you\n    \u003e can consider it as a package manager like composer, npm... To add or define dependencies  \n    \u003e simply edit the dependencies section of the [build.gradle](./build.gradle) file. \n    \u003e Generally in the 'runtime' subsection.   \n \n\n### How to start at boot ?\n\nIf you use the Tomcat deployment it should start by default. With the self-container tomcat, ask google for \"supervisord spring boot\".\n\n### BootRun support\n\nBootRun task is really useful when developping and allows hot reloading when you customize css, html pages...\n\n```shell\n$ ./gradlew bootRun \n# or specify the port with gradle bootRun -Dserver.port=8090\n```\n\nAnd point your browser to [http://localhost:8090](http://localhost:8090).\n\n\n### How to enable the `Java-\u003ePHP` feature ? \n\nBy default this template does not enable `Java-\u003ePHP` by default. So if you intend to\nuse PHP from Java, you must add to the [Application.java](https://github.com/belgattitude/pjb-starter-springboot/blob/master/src/main/java/io/soluble/pssb/Application.java) the following methods:\n  \n  \n```java\n\n\npublic class Application extends SpringBootServletInitializer {\n\n\n    /// Normal initialization sequence\n\n    /**\n     * Register the php.java.servlet.fastcgi.FastCGIServlet\n     * \u003cp\u003e\n     * It replaces the following section found in the original web.xml config:\n     * \u003cp\u003e\n     * \u003cpre\u003e\n     * {@code\n     * \u003cservlet\u003e\n     *     \u003cservlet-name\u003ePhpCGIServlet\u003c/servlet-name\u003e\n     *     \u003cservlet-class\u003ephp.java.servlet.fastcgi.FastCGIServlet\u003c/servlet-class\u003e\n     *     \u003cload-on-startup\u003e0\u003c/load-on-startup\u003e\n     * \u003c/servlet\u003e\n     * \u003cservlet-mapping\u003e\n     *     \u003cservlet-name\u003ePhpCGIServlet\u003c/servlet-name\u003e\n     *     \u003curl-pattern\u003e*.php\u003c/url-pattern\u003e\n     * \u003c/servlet-mapping\u003e\n     * }\n     * \u003c/pre\u003e\n     */\n    @Bean\n    public ServletRegistrationBean phpCGIServletDispatcherRegistration() {\n\n        FastCGIServlet phpJavaServlet = new io.soluble.pjb.servlet.fastcgi.FastCGIServlet();\n        ServletRegistrationBean registration = new ServletRegistrationBean(\n                phpJavaServlet);\n        registration.addUrlMappings(\"*.php\");\n        registration.setLoadOnStartup(0);\n        return registration;\n    }\n\n    /**\n     * Register the php.java.servlet.PhpCGIFilter\n     * \u003cp\u003e\n     * This filter extend the servlet spec 2.2 \"url-pattern\"\n     * to handle PHP PATH_INFO: *.php/something?what=that.\n     * Remove it, if you don't need this feature.\n     * \u003cp\u003e\n     * \u003cpre\u003e\n     * {@code\n     * \u003cfilter\u003e\n     *     \u003cfilter-name\u003ePhpCGIFilter\u003c/filter-name\u003e\n     *     \u003cfilter-class\u003ephp.java.servlet.PhpCGIFilter\u003c/filter-class\u003e\n     * \u003c/filter\u003e\n     * \u003cfilter-mapping\u003e\n     *     \u003cfilter-name\u003ePhpCGIFilter\u003c/filter-name\u003e\n     *     \u003curl-pattern\u003e/*\u003c/url-pattern\u003e\n     * \u003c/filter-mapping\u003e\n     * }\n     * \u003c/pre\u003e\n     */\n    @Bean\n    public FilterRegistrationBean someFilterRegistration() {\n        FilterRegistrationBean registration = new FilterRegistrationBean();\n        registration.setFilter(new io.soluble.pjb.servlet.PhpCGIFilter());\n        registration.addUrlPatterns(\"/*\");\n        //registration.addInitParameter(\"paramName\", \"paramValue\");\n        registration.setName(\"PhpCGIFilter\");\n        registration.setOrder(1);\n        return registration;\n    }\n\n}\n  \n```  \n\nAnd ensure you have the [php-cgi](./docs/install_php-cgi.md) installed and available on your system. \n\nAn example page [main/webapp/index.php](https://github.com/belgattitude/pjb-starter-springboot/blob/master/src/main/webapp/index.php) page is already provided as a starting point.... \nTry [http://localhost:8090/index.php](http://localhost:8090/index.php)\n\n\n### How to enable debugging ?\n\nDebugging can be enabled with the standalone server:\n\n```shell\n$ java -Xdebug -Xrunjdwp:server=y,transport=dt_socket,address=8000,suspend=n \\\n       -jar ./build/libs/JavaBridgeStandalone.jar\n```\n\n## Status\n- [x] Modernized `JavaBridgeTemplate.jar` example\n  - [x] JDK8, spring boot, thymeleaf.\n  - [x] JavaBridgeServlet registered `PHP-\u003eJava`- (from php use the [soluble-japha](https://github.com/belgattitude/soluble-japha) client.\n  - [x] PhpCGIServlet registration example `Java-\u003ePHP` (disabled by default, doc exists)        \n  - [ ] Original PhpJavaBridge config properties in the original web.xml (like location of the php-cgi executable...)        \n- [x] Service landing page \n  - [x] Refactored welcome landing page.\n  - [x] *Ping* address for monitoring.\n  - [ ] Display server/java infos\n- [ ] Documentation \n  - [x] How to customize (WIP)\n  - [ ] Basic security recipes, incl. bind on localhost\n  - [ ] Document how to add local jar deps (out of maven)\n\n\n## Contribute\n\nFeel free to fork and submit pull requests.\n\n\n## Credits\n\n* Initially made with love by [Sébastien Vanvelthem](https://github.com/belgattitude).\n* [Contribute and appears here] \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbelgattitude%2Fpjb-starter-springboot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbelgattitude%2Fpjb-starter-springboot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbelgattitude%2Fpjb-starter-springboot/lists"}