Download the PHP package simplon/jr without Composer

     _                 _                 _
 ___(_)_ __ ___  _ __ | | ___  _ __     (_)_ __
/ __| | '_ ` _ \| '_ \| |/ _ \| '_ \    | | '__|
\__ \ | | | | | | |_) | | (_) | | | |   | | |
|___/_|_| |_| |_| .__/|_|\___/|_| |_|  _/ |_|
                |_|                   |__/

Simplon/Jr

A JSON-RPC Server

Current version: 0.6.5

1. Introduction

1.1. What is JSON?

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. Read on.

1.2. What is RPC?

In computer science, a remote procedure call (RPC) is an inter-process communication that allows a computer program to cause a subroutine or procedure to execute in another address space (commonly on another computer on a shared network) without the programmer explicitly coding the details for this remote interaction. Many different (often incompatible) technologies can be used to implement the concept. Read on.

1.3. Specifications

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format. Read on.

1.4. Request/Response examples

Client request:

Server response:

2. Example setup

The following steps should demonstrate a standard working example of Simplon/Jr. The example setup resides within the test folder which is part of this repo.

2.1. Dependencies

Simplon/Jr is build on top of the php dependency manager Composer. In case composer is not installed do so now, please. It's important that you make yourself familiar with Composer. So take some time and have a look at composer's documentation.

Use your terminal and switch to the test folder. Entering should bring up something similiar to the following:

The file reveals some package details and more importantly it tells Composer about our dependencies:

Ok, enough talk lets install the dependencies via . This should result in some action on your screen which in turn leaves us with our dependencies and some mappings for composer's autoloader class (all within the vendor folder):

2.2. Server

Good, by now we should have our depencies so lets start building our server. To accomplish this we need to make three steps or four in case we want to include authentication. Follow the upcoming steps:

2.2.1. Gateway

First, lets create a . The gateway class defines all requirements for a service setup. Services are separated by a given domain name. For our example we will choose the domain . Therefore, our gateway class resides :

Leaving inheritence and interface implementation aside: what do we see here?

We declare by that the service is enabled by simply returning . Anything else would reject any incoming request for the service. Another interesting method is . Similar to the prior method is authentication either on/off by returning . For now lets assume we have no authentication and lets have a look at . This method returns an array of permitted service requests. Each string is made up of a (e.g. Web), a (e.g. Base) and a . All parts are separated by a dot.

2.2.2. Authentication

Coming back to the above mentioned authentication. If would return the server expects an authentication class within the same directory as the gateway itsself :

The authentication class requires at least one method named . It can hold any number of parameters as long as they are part of the incoming request parameters. Within this method any type of validation can be run. The server expects for a granted access and for a failed authentication.

2.2.3. Service class

In case the gateway is enabled, we pass the authentication (if given) and the incoming service api request matches our valid service list the request will make its way in to the requested service class.

Lets assume the following request has been sent which would reach the following service class :

A service class marks the end of our JSON-RPC server. Our server waits now for a response from the called service class method in order to hand this response back to the client. In our example the server runs the method which returns a string. Our client receives as response.

All other work, for instance a call to our database, should be handled within another class - the so called . Only the result should be given back to our service class so that it can be returned to the client. are slim and stupid while do all the work and magic behind the scenes. This should be always remembered while it supports reusibility of code.

The second method shows you the described technique. The server receives a request with a as parameter. The method takes the parameter and passes it on to a class which will fetch the . How all this happens doesn't matter to the class. All that matters is the username.

Here you see an example skeleton of the mentioned :

2.2.4. Service Bootstrap

Cool, so what's left?

The only thing left to complete our server is a bootstrap file which is used as single-entry-point for a domain service. All what we need is a publically available file which connects to our prior created service gateway :

What does this file? It loads composer's autoloader which in turn enables us to autoload our gateway class. As soon as the gateway is loaded the server reads the incoming request and the above mentioned processed begin to unfold.

2.3. Client

Now that the server is done we need a client which can talk to our service. I wrote a small class called JSONRPC_CURL which makes the request pretty simple. You installed it already at the beginning as it's part of our test folder package.

Our client file can be found here .

To go along with our described example the following code will call our service . Make sure that $urlServiceGateway holds the correct url to your server:

And since we talked about the class here an example:

2.4. Authenticated request

At last here is an example for a authenticated request. Make sure within within your Auth class.

Now lets add the necessary user data to our client:

Missing the required auth data or passing the wrong data will not get you anywhere. Try it out.

License

Cirrus is freely distributable under the terms of the MIT license.

Copyright (c) 2014 Tino Ehrich ([email protected])

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.