Skip to content
Browse files

Updated README and Routing

  • Loading branch information...
1 parent d4e4d93 commit 3333752eb13945011e3279795b1ecdf589b2e668 martin rusev committed Aug 18, 2009
View
14 Emerald/Controller.php
@@ -10,7 +10,7 @@ function Controller($app = null)
}
- /**
+ /*
* Render single file.
* @param string $filename Name of the file to render
* @param array $bindings User variables
@@ -29,7 +29,7 @@ public function render_file($filename, $variables = array())
}
- /**
+ /*
* Render multiple files.
* @param string $filenames Array with files to render
* @param array $variables User variables
@@ -56,6 +56,16 @@ public function render_files($filenames=array(), $variables = array())
}
+ public function render_raw($string)
+ {
+
+ ob_start();
+ echo $string;
+ ob_end_flush();
+
+
+ }
+
View
43 Emerald/Reflection.php
@@ -8,6 +8,7 @@ function __construct($current_url, $apps)
$route = $this->find_route_config($current_url, $apps);
+
if($route == FALSE)
{
$this->find_comment_route($current_url, $apps);
@@ -127,6 +128,7 @@ public function find_comment_route($current_url, $apps)
$directory_structure = scandir($directory);
+
foreach($directory_structure as $key => $file)
{
@@ -142,28 +144,48 @@ public function find_comment_route($current_url, $apps)
/** SCANS METHODS IN CONTROLLER **/
foreach ($methods as $method)
{
+
$method_reflection = new ReflectionMethod($controller, $method->name);
$comments = $method_reflection->getDocComment();
$extract_route = preg_match('/"([^"]+)"/', $comments, $match);
-
+
+
+
if(isset($match[1]))
{
+
$explode_route = explode('/', $match[1]);
$explode_current_url = explode('/', $current_url);
-
+ $match_urls = ($explode_current_url[0] == $explode_route[0]);
- /** TODO rewrite it with real regular expressions **/
- if($explode_route[1] == $explode_current_url[0])
+
+ /** MATCHES '/' **/
+ if($match[1] == '/' && $match_urls == TRUE)
{
+ $data['params'] = '';
+ $data['controller'] = $controller;
+ $data['method'] = $method->name;
+ $data['path'] = $directory;
+ $data['app'] = $value;
+ $this->data = $data;
+ }
+ /** MATCHES EVERYTHING ELSE **/
+ else
+ {
+
+ /** TODO rewrite it with real regular expressions **/
+ if($explode_route[1] == $explode_current_url[0])
+ {
+
$total_route_params = count($explode_route)-2;
$total_current_url_params = count($explode_current_url)-1;
-
+
/** URL MATCHES ONLY WHEN PARAMS IN CURRENT URL AND DEFINED
- * IN THE ROUTE MATCH
- */
+ * IN THE ROUTE MATCH
+ */
if($total_current_url_params == $total_route_params)
{
$data['params'] = array_slice($explode_current_url, 1, $total_route_params);
@@ -172,11 +194,14 @@ public function find_comment_route($current_url, $apps)
$data['path'] = $directory;
$data['app'] = $value;
$this->data = $data;
-
-
+
}
+ }
+
+
+
}
View
1 Emerald/Request.php
@@ -9,7 +9,6 @@ function __construct($url_to_parse, $base_url)
$explode_base = explode('/', $base_url);
$key = array_search(end($explode_base), $explode);
-
$this->current_url = implode('/',array_slice($explode, (int)$key+1));
}
View
176 README.mkd
@@ -7,10 +7,182 @@ It's inspired by frameworks like [Sinatra](http://www.sinatrarb.com/ "Sinatra"),
With Emerald you can create reusable apps and copy them across projects with minimal effort.
Emerald is counterpart to [Crystal](http://crystal.martinrusev.net/ "Crystal"), together they form minimalistic framework stack.
-##Working with Emerald
+## Introduction to Emerald
-Download the latest package from github.
+Building something else, beyond simple apps with microframeworks is a painful process. Emerald is my attempt to solve this problem.
+
+Emerald is build around two ideas, that I borrow from Django - multiple apps and urlpatterns. Besides that with Emerald you can
+prototype your application defining the url parameters like this:
/** get '/' **/
+ function welcome()
+ {
+ $this->render_raw("<html><body>Welcome to my app</body></html>");
+ }
+
+ /** get '/hello/world' **/
+ function hello()
+ {
+
+ $this->render_raw("<html><body>Hello world</body></html>");
+
+ }
+
+## Building your first application
+
+Download the latest package from github. Paste the Emerald package
+in your apache served directory. Open the file **/path/to/Emerald/config/settings.php**
+Edit the line:
+ $config['base_url'] = '';
+
+Add the url to your Emerald project. For example:
+ $config['base_url'] = 'http://localhost/emerald_app';
+
+**Note - your URL must not end with /**
+
+In the **path/to/Emerald/apps/** directory you will find basic hello world app.
+
+The directory structure for you applications is
+ -app_name
+ --controllers
+ --templates
+
+Creating new applications is easy - in the directory **/path/to/Emerald/apps** create new
+directory. For example we want to create mini application dealing with user registration,
+so we create the directory **registration** and 2 sub directories - **controllers** and **templates**
+Now our directory will look like this:
+ /path/to/Emerald/
+ -- apps
+ --welcome
+ --controllers
+ --templates
+ --registration
+ --controllers
+ --templates
+ --config
+ --Emerald
+ --libs
+ .htacess
+ index.php
+
+The next step is to add our registration app in the list with the installed apps. Go to **path/to/Emerald/config/settings.php**
+and in the array
+
+ $config['installed_apps'] = array('welcome');
+
+add our new application like this:
+
+ $config['installed_apps'] = array('welcome','registration');
+
+Now we can begin building our registration application. Create new controller in **path/to/Emerald/registration/controllers**
+Give it whatever name you like. The name convention for your controllers is **NameController.php**. In this case
+our controller will be **RegistrationController.php**. Paste this in our controller:
+
+ class RegistrationController extends Controller
+ {
+
+ function __construct($app)
+ {
+ parent::Controller($app);
+ }
+ }
+
+The variable **$app** is parsed automaticaly as parameter by Emerald, so you can forget about it for now.
+
+### Emerald Routing - Sinatra way
+
+Now let's build our first url mapping function. We want to map www.site.com/registration, this is done by writing this function:
+
+ /** get "/registration" **/
+ function registration()
+ {
+
+ }
+#### Passing parameters to functions
+
+The function name doesn't matter, so you can write whatever you want. Passing parameters in our function is done like this:
+
+ /** get "/user/:id **/
+ function view_user($params = null)
+ {
+ //Now we can access our id
+ $this->id = (int)$params[0];
+
+ }
+
+### Emerald Routing - Django way
+
+Emerald was created with one purpose - help building reusable applications with PHP. So like in Django we have multiple apps
+and url patterns. Building prototypes with Sinatra based routes is OK when you test or create something small. For production
+use this method is slow, because it uses PHP Reflection class, scans every method and runs regular expression against every
+defined in the function comment route. Now let's create the same functions, but this time with url patterns.
+Open the file **path/to/Emerald/config/ursl.php**. There you will se the $urlpatterns array. Delete the test methods
+and define your own:
+
+$urlpatterns = array
+(
+ /** REGISTRATION APP **/
+ '^\/$' => array('path' => 'welcome/registration/registration', 'method' => 'get'),
+ '^user\/\/(\d+)\/$' => array('path' => 'welcome/registration/view_user', 'method' => 'get')
+
+);
+
+**Note In the $urlpatterns array I use the default PHP regular expression. So you must escape the special
+characters like /**
+
+#### Passing parameters to functions
+
+If you want to pass parameters, enclose every parameter with **()**. Emerald will look for this strings and will pass them
+as parameters to your functions. With this routing type you have 3 major advantages:
+
++ Your urls are secure. Malformed url requests will raise errors
++ The parameters passed in the url are only what you need - Integers, strings.
++ You can design your urls to whatever you want, without the limitation to parse parameters only at the end
+
+For example you can write:
+
+$urlpatterns = array
+(
+ /** REGISTRATION APP WITH LANGUAGE SUPPORT **/
+ '^([a-z0-9])\/user\/\/(\d+)\/$' => array('path' => 'welcome/registration/view_user', 'method' => 'get')
+
+);
+
+
+### Templates
+
+The default templates directory in Emerald is **/path/to/Emerald/apps/our_app/templates/**
+
+#### Rendering templates
+
+Rendering templates in Emerald is easy.It is done like this:
+
+ $this->render_file('template_name');
+
+You can render multiple templates with the function `render_files()` like this:
+
+ $this->render_files('header','content','footer');
+
+Or we can render raw html strings:
+
+ $this->render_raw('<html><body>Hello world</body></html>);
+
+
+### Passing variables to templates
+
+Passing variables from our functions to the template is done in a way similar to Codeigniter.
+Defining our variables is done in one global data array:
+
+ $data['variable'] = 'My first variable';
+
+ $this->render_file('template',$data);
+
+
+ // in template.php
+ <?php echo $variable; ?>
+
+
+That completes my tutorial on Emerald. For more information and examples,
+go to [emerald.martinrusev.net](http://emerald.martinrusev.net/ "Emerald")
View
48 apps/welcome/controllers/HelloController.php
@@ -0,0 +1,48 @@
+<?php
+
+class HelloController extends Controller
+{
+
+ function __construct($app)
+ {
+ parent::Controller($app);
+ }
+
+
+ /** get "/" */
+ function home_page($params = null)
+ {
+ $data['emerald'] = 'Emerald';
+
+
+
+ $this->render_file('hello', $data);
+
+ }
+
+
+ /** get "/hello/:world/" */
+ function martin($params = null)
+ {
+ $data['string'] = $params[0];
+
+ $this->render_file('params', $data);
+
+
+ }
+
+
+ function new_tasklist()
+ {
+
+ $this->render_file('empty');
+ }
+
+
+
+
+
+
+
+
+}
View
1 apps/welcome/templates/empty.php
@@ -0,0 +1 @@
+Hello
View
2 apps/welcome/templates/hello.php
@@ -1 +1 @@
-Hello world
+<h1>Hello world from <?php echo $emerald; ?></h1>
View
1 apps/welcome/templates/params.php
@@ -0,0 +1 @@
+<h1>Hello <?php echo $string; ?></h1>
View
9 config/settings.php
@@ -6,14 +6,5 @@
/** APPLICATION SPECIFIC VARIABLES **/
-
-/**
- * If TRUE you don't need to escape '\'
- * FOR EXAMPLE : ^todo/new/$ is valid regular expression,
- * that will be converted automaticaly to PHP regex pattern : ^todo\/new\/$
- *
- */
-$config['django_regex'] = TRUE;
-
$config['base_url'] = '';
View
2 config/urls.php
@@ -2,7 +2,7 @@
$urlpatterns = array
(
/** WELCOME APP **/
- '^todo\/new\/$' => array('path' => 'welcome/tasks/new_tasklist', 'method' => 'get'),
+ '^todo\/new\/$' => array('path' => 'welcome/hello/new_tasklist', 'method' => 'get'),
'^todo\/delete_task\/(\d{1})\/(\d+)\/$' => array('path' => 'welcome/tasks/new_tasklist', 'method' => 'get')
);
View
3 index.php
@@ -21,6 +21,8 @@
}
$route = new Emerald_Request($current_url, $config['base_url']);
+
+
$find_route = new Emerald_Reflection($route->current_url, $config['installed_apps']);
@@ -38,4 +40,3 @@
{
Response::raise404();
}
-

0 comments on commit 3333752

Please sign in to comment.
Something went wrong with that request. Please try again.