Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 113 lines (89 sloc) 9.807 kB
cdd04e3 @evantahler Update readme.markdown
authored
1 *I will not be doing much more work on this framework. However, many of the philosophies and syntax are used in the [nodeJS](http://nodejs.org) successor to this project. Check it out @ [https://github.com/evantahler/actionHero](https://github.com/evantahler/actionHero)*
0386a5d @evantahler Update readme.markdown
authored
2
eae499b @evantahler Update readme.markdown
authored
3 [![Endore Me](http://api.coderwall.com/evantahler/endorsecount.png)](http://coderwall.com/evantahler)
4
6dec6fb readme => markdown
Evan Tahler authored
5 Who is _DAVE_?
6 ============
7
94d1048 adding QuickStart
Evan Tahler authored
8 DAVE is a minimalist, multi-node, transactional API framework written in PHP
6dec6fb readme => markdown
Evan Tahler authored
9
d3cdeca @evantahler Edited readme.markdown via GitHub
authored
10 Dave contains an end-to-end API test suite for TDD, a Task model, an Active Database Model, and a stand-alone development server ( PHP) to get you started.
11
72b9feb @evantahler Edited readme.markdown via GitHub
authored
12 DAVE is an acronym that stands for Delete, Add, Edit, and View. These 4 methods make up the core functionality of many transactional web applications. The DAVE API aims to simplify and abstract may of the common tasks that these types of APIs require. DAVE does the work for you, and he's not CRUD. Dave was built to be both easy to use, but to be as simple as possible. I was tired of bloated frameworks that were designed to be monolithic applications which include M's, V's, and C's together in a single running application. As applications grow and become more 'service oriented', this is the eventual route which many applications go. I wanted to make is as simple as possible to create a new application with this mindset, and to allow for future flexibility.
6dec6fb readme => markdown
Evan Tahler authored
13
b10f4fa @evantahler readme update
authored
14 The DAVE API defines a single access point and accepts GET, POST, or COOKIE input. You define "Action's" that handle the input, such as "AddUser" or "GeoLocate". The DAVE API is NOT "RESTful", in that it does not use the normal verbs (Get, Put, etc) and uses a single /path/. This was chosen to make it as simple as possible for devices/users to access the functions, including low-level embedded devices which may have trouble with all the HTTP verbs. To see how simple it is to handle basic actions, this package comes with a basic user system included. Look in `/Actions/examples` to see the logic behind adding, editing, viewing, and deleting users. This includes log in. Restful paths are optional if you really must have them, and be defined per Action.
6dec6fb readme => markdown
Evan Tahler authored
15
94d1048 adding QuickStart
Evan Tahler authored
16 The DAVE API understands 2 types of security methodology. "Public" actions can be called by anyone, and then can implement optional user-based security (checking userIDs and PasswordHashes?). Optionally, certain Actions can be defined as "Private", and will require a defined developer to authenticate with every request. This requires your developers to provide an MD5 hash of their APIKey and private DeveloperID to authenticate with. You can mix private and public actions. Of course, you can make your own actions for this as well!
6dec6fb readme => markdown
Evan Tahler authored
17
72b9feb @evantahler Edited readme.markdown via GitHub
authored
18 Dave contains an end-to-end API test suite for TDD, a Task model, an Active Database Model, and a stand-alone development server (written in just PHP) to get you started.
19
94d1048 adding QuickStart
Evan Tahler authored
20 Philosophical Questions
21 -----------------------
22
23 If you have ever asked these questions of other web-frameworks, then DAVE might be the right fit for you:
7a80563 adding QuickStart
Evan Tahler authored
24
94d1048 adding QuickStart
Evan Tahler authored
25 * Why do we really need a controller?
26 * Why are linear actions so hidden in object abstraction?
27 * Why can't I de-couple my M's, V's and C's?
28 * Why can't my test suite use the real application?
29 * Is there an option for a non-restFUL API?
30 * Why isn't there an easier way to develop and test locally with PHP?
31 * Why are there no modern PHP API Frameworks?!
6dec6fb readme => markdown
Evan Tahler authored
32
33 Features
34 --------
35 * Abstraction of basic DAVE (Delete, Add, Edit, View) actions
36 * Active Database Modeling on-the-fly or fixed per your requirements
94d1048 adding QuickStart
Evan Tahler authored
37 * (optional) Objects for Database entities with DAVE abstraction
6dec6fb readme => markdown
Evan Tahler authored
38 * Built with a Multi-Node system in mind, but works great on a single machine as well
39 * Developer-based authentication in tandem with user-level authentication
40 * Rate Limiting for client connections
41 * Class-based abstraction of mySQL connections
42 * Built-in support for multiple types of Caching (Flat File, mySQL, memcache)
43 * CRON processing of delayed events
44 * Simple error handling and input sanitization
45 * XML, JSON, Serialized PHP output types built in
d0606a3 adding note about Tasks to readme
Evan Tahler authored
46 * Task Classes to automate periodic management and to ease development
6dec6fb readme => markdown
Evan Tahler authored
47 * End-to-end spec testing framework for the API including custom assertions
48
0166325 @evantahler Edited readme.markdown via GitHub
authored
49 Stand-Alone Development Webserver written in PHP
6dec6fb readme => markdown
Evan Tahler authored
50 -----------------------------------------------------------------------------------
94d1048 adding QuickStart
Evan Tahler authored
51 To help with development, a single-threaded multi-request webserver is a part of this project. This will allow you to locally run this framework in "development mode". This webserver is written entirely in PHP and has support for basic static file-types (css, js, images, html) along with the sand-boxed execution of PHP scripts (including all of those required for this framework.). The server currently provides the normal $_GET, $_POST, $_COOKIE, $_REQUEST arrays and a basic emulation of $SERVER. Due to metaprogramming limitations in the default PHP installs on most servers/machines, it is impossible to modify the behavior of header() and setcookie(). To remedy this, please use _header() and _setcookie() in your DAVE projects. These functions will first attempt to use the default versions of these functions, and if they fail (AKA when using the StandAlone server), will emulate their behavior in other ways. This server implementation was inspired by nginx and rails unicorns, and makes use of spawning OS-level processes to do the heavy lifting for each request.
52
53 You certainly don't need to use the bundled SERVER to run dave. For production deployment, upload DAVE to `/var/www/html` (or however you normally deploy). The SERVER was included to allow for local test-driven development common to other frameworks/languages to which the modern web developer may be accustomed too.
c94835b readme => markdown
Evan Tahler authored
54
55 Run "php SERVER.php" from within the project directory to get started. Point your browser at http://localhost:3000
6dec6fb readme => markdown
Evan Tahler authored
56
57 Requirements
58 ------------
428d028 updating CONFIG and cleaning paths. PHP 5.3 required now
Evan Tahler authored
59 * PHP 5.3+
f2976d2 @evantahler Edited readme.markdown via GitHub
authored
60 * mySQL 5+
0166325 @evantahler Edited readme.markdown via GitHub
authored
61
62 However, for production deployment, your traditional LAMP stack is best.
63
6dec6fb readme => markdown
Evan Tahler authored
64
65 Actions you can try [[&Action=..]] which are included in the framework:
66 -----------------------------------------------------------------------
67 * DescribeActions: I will list all the actions available to the API
68 * DescribeTables: I am an introspection method that will show the results of the auto-described available tables and cols. I will show weather or not a col is required and if it is unique
69 * CacheTest: Send a Hash [[ &Hash=MyString ]] and I will first store it in the cache, and on subsequent calls retrieve the vale from the cache until expired. Change the value of the Hash and note the old value will be displayed until it expires
70 * LogIn: Example user system. Follow returned error messages.
71 * UserAdd: Example user system. Follow returned error messages.
72 * UserDelete: Example user system. Follow returned error messages.
73 * UserEdit: Example user system. Follow returned error messages.
74 * UserView: Example user system. Follow returned error messages.
75 * ObjectTest: An example of on-the-fly database object manipulation. Check the code for this file to see how simple it is.
76 * CookieTest: Will set cookies in your browser. Use this to test SERVER's implementation of _setcookie()
77 * SlowAction: A simple action that will sleep for a number of seconds. Use this to test SERVER's non-blocking implementation by making a slow request, and then other requests to ensure that a slow request will not block other actions from processing.
78
e77f636 @evantahler moving example server to phpfog
authored
79 Example Site: [http://php-dave-api.phpfogapp.com/](http://php-dave-api.phpfogapp.com/)
6c46354 @evantahler Edited readme.markdown via GitHub
authored
80
e77f636 @evantahler moving example server to phpfog
authored
81 Or try the interactive API explorer here (html included in /examples): [http://php-dave-api.phpfogapp.com/examples/api_explorer.html](http://php-dave-api.phpfogapp.com/examples/api_explorer.html)
6dec6fb readme => markdown
Evan Tahler authored
82
d84ef0b adding QuickStart
Evan Tahler authored
83 QuickStart
84 ----------
94d1048 adding QuickStart
Evan Tahler authored
85 You can get started on your local machine in 5 minutes! This tutorial is for Unix-like machines (OSX OK!). We'll be using the included stand-alone server for development. You certainly don't need to use the bundled SERVER to run dave. For production deployment, upload DAVE to `/var/www/html` (or however you normally deploy).
043f0cf adding QuickStart
Evan Tahler authored
86
6f53f2c adding QuickStart
Evan Tahler authored
87 * Instal PHP (OSX users already have it, Linux folks yum/apt install php5)
88 * Install mySQL 5 [OSX: http://www.mysql.com/] [Linux: yum/apt install mysql-server and mysql-client)
94d1048 adding QuickStart
Evan Tahler authored
89 * Get clone this project
90 * `git clone git://github.com/evantahler/PHP-DAVE-API.git /path/where/you/want/it` OR just hit the `download` button above
6fe6c3e adding QuickStart
Evan Tahler authored
91 * Rename `/API/CONFIG.example.php` to `/API/CONFIG.php`
6f53f2c adding QuickStart
Evan Tahler authored
92 * Configure CONFIG.php. Assuming we will be running mySQL locally as root with no password, all you should need to change is:
5bbde0c @evantahler cleanup, renamiing, documentation
authored
93 * `$CONFIG['SystemTimeZone']` (check http://www.php.net/manual/en/timezones.php for how to define your timezone)
6f53f2c adding QuickStart
Evan Tahler authored
94 * `$CONFIG['App_dir']` (this is where the /API folder is)
95 * setup mySQL for DAVE
96 * create a mysql database called "daveapi"
97 * (from the command line)
94d1048 adding QuickStart
Evan Tahler authored
98 * `mysql -u root`
99 * `create database daveapi;`
100 * `exit`
6f53f2c adding QuickStart
Evan Tahler authored
101 * load in the default tables
94d1048 adding QuickStart
Evan Tahler authored
102 * `mysql -u root daveapi < BaseDBs/API_WITH_USER_TABLE.sql`
103 * Install the CRON.php file to run on a set frequency. Note that paths have to be absolute.
104 ** `crontab -e`
105 ** `*/1 * * * * /usr/bin/php /path/to/CRON.php > /path/to/CRON_LOG.txt`
6f53f2c adding QuickStart
Evan Tahler authored
106 * start up the webserver
107 * `php /SERVER/SERVER.php`
108 * Visit Dave
109 * Browser: `http://localhost:3000&OutputType=XML`
110 * CURL + time: `time curl -v http://127.0.0.1:3000/ -d "OutputType=XML"`
1fa11c2 @evantahler Edited readme.markdown via GitHub
authored
111 * Use the API console `script/api --Action=DescribeActions`
d84ef0b adding QuickStart
Evan Tahler authored
112
ac886c9 adding the Rollback param to requests
Evan Tahler authored
113 That's it! You should see JSON and XML output that describes all of the actions that the server could preform, and an Error asking you to supply an action. Give `http://localhost:3000/?OutputType=XML&Action=ObjectTest` or `http://localhost:3000/?OutputType=PHP&Action=SlowAction` a try to see some basic examples.
Something went wrong with that request. Please try again.