{"id":14985385,"url":"https://github.com/luracast/restler","last_synced_at":"2025-05-14T05:10:45.627Z","repository":{"id":45243107,"uuid":"1588366","full_name":"Luracast/Restler","owner":"Luracast","description":"Simple and effective multi-format Web API Server to host your PHP API as Pragmatic REST and/or RESTful API","archived":false,"fork":false,"pushed_at":"2024-09-23T14:36:14.000Z","size":9743,"stargazers_count":1360,"open_issues_count":40,"forks_count":316,"subscribers_count":87,"default_branch":"master","last_synced_at":"2024-10-29T15:22:10.238Z","etag":null,"topics":["composer","html-format","json-format","jsonp","php","php-fpm","phpdoc-comments","restler"],"latest_commit_sha":null,"homepage":"http://luracast.com/products/restler/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Luracast.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://www.paypal.com/paypalme/luracast"]}},"created_at":"2011-04-08T17:39:58.000Z","updated_at":"2024-10-23T12:54:31.000Z","dependencies_parsed_at":"2023-10-01T15:24:34.423Z","dependency_job_id":"7254cfd3-4eba-4a38-821c-56264f4a9c9b","html_url":"https://github.com/Luracast/Restler","commit_stats":{"total_commits":1414,"total_committers":45,"mean_commits":31.42222222222222,"dds":"0.10042432814710045","last_synced_commit":"dde49c566e5bb4266634ef2748c79747134d8c4e"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luracast%2FRestler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luracast%2FRestler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luracast%2FRestler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Luracast%2FRestler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Luracast","download_url":"https://codeload.github.com/Luracast/Restler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076850,"owners_count":22010611,"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":["composer","html-format","json-format","jsonp","php","php-fpm","phpdoc-comments","restler"],"created_at":"2024-09-24T14:10:51.131Z","updated_at":"2025-05-14T05:10:45.604Z","avatar_url":"https://github.com/Luracast.png","language":"JavaScript","readme":"![Restler](public/examples/resources/restler.svg) Luracast Restler\n==================================================================\n[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/Luracast/Restler)\n[![Latest Stable Version](https://poser.pugx.org/luracast/restler/v/stable.png)](https://packagist.org/packages/luracast/restler)\n[![Total Downloads](https://poser.pugx.org/luracast/restler/downloads.png)](https://packagist.org/packages/luracast/restler)\n[![Latest Unstable Version](https://poser.pugx.org/luracast/restler/v/unstable.png)](https://packagist.org/packages/luracast/restler)\n[![License](https://poser.pugx.org/luracast/restler/license.png)](https://packagist.org/packages/luracast/restler)\n\n### Version 5\n\n\u003e upgraded from version 3 RC6 for latest PHP support\n\nRestler is a simple and effective multi-format Web API Server written in PHP.\n\nJust deal with your business logic in php, restler will take care of the REST!\n\n### Restler - *Better APIs by Design*\n\n* [Developer Home](https://luracast.com/products/restler/)\n* [Documentation](https://restler5.luracast.com/) with live examples\n* Updates on [Facebook](https://www.facebook.com/Luracast) and [Twitter](https://twitter.com/Luracast)\n* [Features](#features)\n* [Installation](#installation)\n* [Quick Start Guide](#quick-start-guide)\n* [Change Log](#change-log)\n\nFeatures\n--------\n\n* No Learning Curve\n* Light weight\n* Flexible\n* Highly Customizable\n* Many Examples that can be tried on your localhost to get started\n* Supports HTTP request methods HEAD, GET, POST, PUT, DELETE, OPTIONS and PATCH via header or request parameter (method)\n* Supports both RESTful and Pragmatic REST API Design\n* Clients can use X-HTTP-Method-Override header, supports Cross Origin Resource Sharing and JSONP\n* Two-way format(media type) conversion both send and receive\n    * Pluggable content Formatter framework and api\n    * Comes with JSON, XML, Yaml, Amf, and Plist(both XML and Binary) format support\n* Pluggable Authentication schemes\n    * OAuth 2 Server\n* Pluggable Filters to effectively manage API usage\n    * API Rate Limiting Filter\n* Routing\n    * Manual Routing (Annotation)\n        * Using `@url GET my/custom/url/{param}` PHPDoc comments\n    * Auto Routing (Reflection)\n        * URL to Method mapping\n        * URL part to Method parameter mapping\n        * Query parameters to Method parameter mapping\n        * Request body to Method parameter mapping\n* Cache built-in\n    * Client Side Caching support\n    * Proxy Caching support\n* API Features\n    * Always supports URLEncoded format for simplified input (POST vars)\n    * Automatic parameter validation and type conversion\n    * API versioning support by URL and/or vendor specific MIME\n    * API documentation and discovery using [Restler API Explorer](https://github.com/Luracast/Restler-API-Explorer)\n    * Throttling and Performance tuning\n* Management\n    * Behavior Driven API testing using [Behat](http://behat.org/) and [Guzzle](https://github.com/guzzle/guzzle)\n    * Command line Project Management using [Respect/Foundation](https://github.com/Respect/Foundation)\n    * Dependency Management using [Composer](http://getcomposer.org/)\n    * Source code distributed under LGPL\n\nGit Repository and the Branches\n-------------------------------\n\n1. Most stable and recent version is at the `master` branch, previous versions are in the version branches such\n   as `v4`, `v3`, `v2`, and `v1`.\n\n2. Version branch with the current version such as `v5` is used for building up the next release. It's documentation may\n   not be updated frequently and thus reserved for the daring ones.\n\n3. Feature branches such as `features/html` and `features/router` are purely for experimentation purpose to try out a\n   feature. They may be merged when ready.\n\nTest Drive\n----------\n\nInstall this repository to try out the examples.\n\n\u003e Make sure PHP 5.4 or above is available on your server. We recommended using the latest version for better performance.\n\n### 1. Install Composer\n\nRestler uses [Composer](http://getcomposer.org/) to manage its dependencies. First, download a copy of `composer.phar`.\nIt can be kept in your project folder or ideally in `usr/local/bin` to use it globally for all your projects. If you are\non Windows, you can use the composer\n[windows installer](https://getcomposer.org/Composer-Setup.exe) instead.\n\n### 2. Install Restler\n\n#### Option 1. Using composer create-project\n\nYou may install Restler by running the create project command in your terminal. Replace {projectName} with your actual\nproject name. It will create a folder with that name and install Restler.\n\n```console\nphp composer.phar create-project luracast/restler {projectName}\n```\n\n\u003e **Note:-**\n\u003e\n\u003e 1. If you do not want the additional formats and BDD tools you can include\n     \u003e    `--no-dev` to enforce exclusion of dev packages.\n\u003e\n\u003e 2. If you want to try the bleading edge v3 branch or any of the feature\n     \u003e    branches include `3.x-dev` or `dev-features/html` in the above command\n\n#### Option 2. Downloading from GitHub\n\nAfter installing Composer, download the [latest version]() of the Restler framework and extract its contents into a\ndirectory on your server. Next, in the root of your Restler project, run the `php composer.phar install`\n(or `composer install`) command to install all the framework's dependencies. This process requires Git to be installed\non the server to successfully complete the installation.\n\nIf you want to update the Restler framework, you may issue the\n`php composer.phar update` command.\n\n\u003e **Note:-** If you are not allowed to install composer and git on your server, you\n\u003e can install and run them on your development machine. The resulting files and\n\u003e folders can be uploaded and used on the server.\n\n### 3. Configure\n\nIdeally public folder should be mapped as your web root, It is optional, but recommended avoiding exposing unneeded\nfiles and folders.\n\n### 4. Try it out\n\nTry the live examples in your localhost. \n\u003e You may launch the PHP's built-in server with `composer serve` command.\n\n### 5. Run some test\n\nUpdate the base_url specified in `behat.yml` and then try the following command\n\n```console\n\nvendor/bin/behat\n\n```\n\u003e alternatively you can run `composer test`\n\nThis will test the examples against the behaviors expected, for example\n\n```gherkin\n\nFeature: Testing CRUD Example\n\n  Scenario: Creating new Author with JSON\n    Given that I want to make a new \"Author\"\n    And his \"name\" is \"Chris\"\n    And his \"email\" is \"chris@world.com\"\n    And the request is sent as JSON\n    When I request \"/examples/_007_crud/authors\"\n    Then the response status code should be 200\n    And the response should be JSON\n    And the response has a \"id\" property\n\n```\n\nAll set, Happy RESTling! :)\n\nQuick Start Guide\n-----------------\n\nWe have two options to create your own restler api server\n\n 1. Most convenient option is using application templates such as [Restler Application](https://github.com/Luracast/Restler-Framework) \n    which has integrations with many packages to help us with the business logic as well. \n    If you choose this option, select a branch in that repository and proceed with \n    the instructions available there.\n    \n 2. Create a project from scratch so that you have full control over every aspect of your application. \n    If you choose this option, follow along with the steps below.\n    - create a folder to hold your project and open it in the terminal.\n    - run `composer init` and follow along to create `composer.json`\n    - when it is asking for dependencies, type `restler/framework` and `^5` for the version constraint.\n    - alternatively, you can leave it blank and create the composer.json first and then run `composer require restler/framework:^5`\n    \n\u003e we are using `restler/framework` instead of `luracast/restler` to reduce the space required for the package. \n\u003e It is coming from https://github.com/Luracast/Restler-Framework it contains only the contents of src folder here.\n    \n\u003e Even when you are building from scratch, checking out the application templates will help with folder structure \n\u003e decisions and finding other useful packages.\n\n### 1. Write API\n\nCreate your **API classes** with all needed public and protected methods\n\n### 2. Open the Gateway\n\nCreate the **gateway (public/index.php)** as follows\n\n```php\n\u003c?php\nrequire_once __DIR__.'/../vendor/autoload.php';\n\nuse Luracast\\Restler\\Restler;\n\n$r = new Restler();\n$r-\u003eaddAPIClass('YourApiClassNameHere'); // repeat for more\n$r-\u003ehandle(); //serve the response\n```\n\n### 3. Prettify URLs\n\n**Enable URL Rewriting**\n\nMake sure all the requests go to index.php by enabling URL Rewriting for your website\n\nFor example:-\n\nIf you are on Apache, you can use an .htaccess file such as\n\n```apache\nDirectoryIndex index.php\n\u003cIfModule mod_rewrite.c\u003e\n    RewriteEngine On\n    RewriteRule ^$ index.php [QSA,L]\n    RewriteCond %{REQUEST_FILENAME} !-f\n    RewriteCond %{REQUEST_FILENAME} !-d\n    RewriteRule ^(.*)$ index.php [QSA,L]\n\u003c/IfModule\u003e\n\u003cIfModule mod_php5.c\u003e\n    php_flag display_errors On\n\u003c/IfModule\u003e\n```\n\n\u003e **Note:-** This requires `AllowOverride` to be set to `All` instead of `None`\n\u003e in the `httpd.conf` file, and might require some tweaking on some server\n\u003e configurations. Refer to [mod_rewrite](http://httpd.apache.org/docs/current/mod/mod_rewrite.html)\n\u003e documentation for more info.\n\nIf you are on Nginx, you have to make sure you set the `server_name` and pass the PHP scripts to fast cgi (PHP-FPM)\nlistening on 127.0.0.1:9000\n\n```\nserver {\n    listen        80;\n    server_name   api.luracast.com; //change it to match your server name\n\n    //... other stuff\n\n    location ~ \\.php$ {\n        root           /var/www/html;\n        fastcgi_pass   127.0.0.1:9000;\n        fastcgi_index  index.php;\n        fastcgi_param  SCRIPT_FILENAME  /var/www/html/$fastcgi_script_name;\n        include        fastcgi_params;\n    }\n\n    //... other stuff\n}\n```\n\n\u003e **Note:-** This requires PHP, PHP-FPM to be properly installed and configured.\n\u003e Refer to [PHP FastCGI](http://wiki.nginx.org/PHPFcgiExample) example for more\n\u003e info.\n\n### 4. Customise\n\n**Fine tune to suit your needs**\n\n```php\n\u003c?php\nrequire_once __DIR__.'/../vendor/autoload.php';\nuse Luracast\\Restler\\Restler;\nuse Luracast\\Restler\\Defaults;\n//set the defaults to match your requirements\nDefaults::$throttle = 20; //time in milliseconds for bandwidth throttling\n//setup restler\n$r = new Restler();\n$r-\u003eaddAPIClass('YourApiClassNameHere'); // repeat for more\n$r-\u003eaddAPIClass('Explorer'); //from restler framework for API Explorer\n$r-\u003eaddFilterClass('RateLimit'); //Add Filters as needed\n$r-\u003ehandle(); //serve the response\n```\n\nExplore the api and try it out by openings `explorer/index.html` from the web root on your browser\n\nHappy Exploring! :)\n\n\u003e **Note:-** Using eAccelerator can make restler to fail as it removes the\n\u003e comments. More info can be found [here](http://wildlyinaccurate.com/eaccelerator-and-doctrine-2)\n\n### 5. Annotate\n\nRestler supports annotations in the form of PHPDoc comments for API fine tuning\n\nThey are documented in detail under [Annotations](ANNOTATIONS.md)\n\n### 6. Authorize\n\nIn order to protect your api, authenticate and allow valid users\n\n```php\n\u003c?php\nrequire_once '../restler.php';\nuse Luracast\\Restler\\Restler;\n$r = new Restler();\n$r-\u003eaddAPIClass('YourApiClassNameHere'); // repeat for more\n$r-\u003eaddAuthenticationClass('CustomAuth'); //Add Authentication classes as needed\n$r-\u003ehandle(); //serve the response\n```\n\n### 7. Start Production\n\nBy default Restler runs in debug mode more fine tuned for API developer, by showing detailed error messages and\nprettifying the api result to human readbale form\n\nBy turning on production mode you will gain some performance boost as it will cache the routes (comment parsing happens\nonly once instead of every api call), few other files and avoid giving out debug information\n\n```php\n\u003c?php\nrequire_once '../restler.php';\nuse Luracast\\Restler\\Restler;\n\n//setup restler\n\n$r = new Restler(true); //turn on production mode by passing true.\n//If you are using file based cache (the default) make sure cache folder is\n//writable. when you make changes to your code make sure you delete the\n// routes.php inside the cache folder\n//...\n```\n\u003e*Note:-* When production mode is set to `true` it always uses the cache and does not detect \n\u003e changes and new routes if any. Your continuous integration pipeline or your git hook should delete \n\u003e this file during the deployment process. Alternatively you can pass second parameter to restler\n\u003e constructor to refresh the cache when changes need to be applied.\n\nChange Log\n----------\n\n### Restler 5\n\n* Semantic versioning to move forward\n* Support for PHP 8\n* Corrects the source path to be outside the vendor directory\n* Adds php development server support with `composer serve` command.\n* Ability to run the tests with `composer test` command after running the server \n  with `composer serve` in another window.\n\n### Restler 3.0 RC6\n\n#### What's new\n\n* Adds PassThrough class to serve files outside your web root, including secure downloads\n* Adds Explorer class (v1 swagger 1.2 spec, and v2 swagger 2.0 spec) as a potential \n  replacement to Resources class (swagger 1.1 spec)\n    * Explorer comes bundled with the html, css, and assets. So that you need not manually download and configure it\n    * Explorer combines the parameters that are expected in the request body to create a unique model for swagger\n    * Since Restler Explorer comes bundled, you can map to it to your url of choice. \n      For example `$restler-\u003eaddAPIClass(\"Luracast/Restler/Explorer\", 'swagger')` maps it to `/swagger`.\n    * Explorer metadata can be easily customized with ExplorerInfo class\n\n#### Improvements\n\n* Routes class improved to provide a findAll method to list all the routes for a specific version of the API excluding\n  the specified paths and http methods.\n* The magic properties utilized by routes when found, ignoring actual properties. \n  This is useful for Dynamic Model classes such as Eloquent.\n* Routes now allow `@required` and `@properties` to be arrays when the parameter is an object. \n  This helps us to pick and choose the properties for each api method differently.\n  Example `{@properties property1,property2,property3}` `{@required property1,property2}` makes an api to only look for\n  3 properties and 2 of them are required.\n\n* Optimized the Nav class. It now makes use of `Routes::findAll()`, along with Explorer class\n* Restler class has setBaseUrls method to set acceptable base urls that can be set using `$_SERVER['HTTP_HOST']`.\n  Read [this article](http://shiflett.org/blog/2006/mar/server-name-versus-http-host) to understand why. This is useful\n  in the following cases when\n    * PHP has trouble detecting the port correctly\n    * multiple domains are pointing to the same server\n\n* Restler class now allows overriding the status code by setting `$this-\u003erestler-\u003eresponseCode` from the api method.\n* Improved Forms class to send the embedded properties to emmet template. For example\n\n```\n/**\n * {@id form1}\n *\n * @param string $name\n * @param int $age\n*/\n```\n\n  Generates the following form\n\n    \u003cform role=\"form\" id=\"form1\" method=\"POST\" ...\n\n  because the emmet template has id in it (see below)\n\n    form[role=form id=$id# name=$name# method=$method# action=$action# enctype=$enctype#]\n\n* Forms class uses embedded properties with `@param` comments to set html attributes (for example id, accept etc) easily\n* FormStyles improved.\n* Validator is now initialized by scope so that we can set its properties with `@class` comment. **Example:\n  -**  `@class Validator {@holdException}` makes the validator to hold the exceptions instead of throwing\n* Improved Form validation with error messages for individual fields.\n* Forms example updated to show validation errors with bootstrap based themes.\n* CommentParser is now able to parse `@property`, `@property-read`, `@property-write` to support documenting the dynamic\n  properties.\n* CommentParser supports short array syntax such as `string[]`, `DateTime[]`\n* Scope adds support for external DI Container of your choice with `Scope::$resolver` property.\n* Renamed `String` class to `Text` for PHP 7 support (String is a reserved keyword in php7)\n* Flash now implements ArrayAccess so that we can access flash variables just like an array\n* **composer.json**: removed many dependencies from require-dev. Will prompt the developers to install them individually\n  when they need them.\n* newrelic support added.\n* Memcache support added.\n","funding_links":["https://www.paypal.com/paypalme/luracast"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluracast%2Frestler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluracast%2Frestler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluracast%2Frestler/lists"}