simply put: Your First App - This is a walk-through tutorial. The rest of the guide explains.

Starting your app

In this tutorial, we will create a basic app, and illustrate the things you'll need to do for every new app you create. Make a copy of the myApp folder and place it anywhere you like. Name it anything you like. This will be the folder housing your app, and we will refer to it as the APP_DIR folder.

Local folder

Whether you are working with a team or not, you will probably want to use version control software to keep backups of your project.

PHP ON PIE recognizes that some things are specific to your local development environment, and should not be checked into version control. This includes things like absolute pathnames, database credentials, and API keys. For this purpose, PIE apps have the APP_DIR/local folder.

Copy the APP_DIR/local.sample folder to APP_DIR/local. You can add the APP_DIR/local.sample folder to version control, and it will serve as a template that you will have to modify on each machine where you install the app. In this way, your app is like every other portable PHP application.

Serving your app to the web

The next step is to serve the APP_DIR/web folder to the web, using a web server with PHP support, such as Apache + PHP, Litespeed, or something else. You can do this in any one of the following ways:

• make a symbolic link to APP_DIR/web in your web server's httpdocs directory
  (does not work on Windows)
• add an Alias directive to your server's configuration file, pointing to APP_DIR/web
• add a "virtual server" for a particular hostname, and set its document root to APP_DIR/web.
  You'll probably want to do this for professional websites.

Be sure to set permissions so your web server can read the files in your APP_DIR/web folder.

The APP_DIR/web folder comes with an .htaccess file for Apache, telling it to reroute all non-file requests to your app's index.php script. If this is working, you'll be able to access your app from URLs like:

http://yourdomain.com/yourApp/welcome

Otherwise, until you set up URL rewriting on your webserver, you will use URLs like this:

http://yourdomain.com/yourApp/index.php/welcome

If you've done the above steps, you can now navigate to your app in the browser and see a basic welcome page. If you see some instructions instead, they are reminding you of what you still have to do.

Config

PHP ON PIE uses JSON for its configuration system. Your app's config file is APP_DIR/config/app.json.

Let's give our app a unique name. You do this by setting the pie/app config field. It is a good idea to use a short name that can double as a variable name, such as "youMixer" or "dating". (Cool fact: in the future, you'll be able to package your work into a plugin with that name.)

Change the routes

Now, let's change the routes used for translating URLs from web requests into internal URIs for PIE. In the config file, search-and-replace every occurrence of myApp with the name of your app.

If you go to the browser and refresh the app, you will see an error. This demonstrates two things:

• When trying to generate a response, uncaught exceptions are printed by PIE like you see on the screen, allowing you to debug and fix them.
• The exception occurred because now, the empty tail "" translates to the "$app/welcome" URI (where $app is your app's name). And you have not yet written the code to handle this and generate some output. Let's do that now.

Handling your first requests

Let's assume your app was named youMixer. To create a handler for the "youMixer/welcome" URI, do the following:

1. Make a new folder, APP_DIR/handlers/youMixer
2. In it, make a folder, welcome
3. Inside that, make a folder response
4. In this folder, create a PHP file, content.php

Put the following code into our PHP file:

<?php

function youMixer_welcome_response_content()
{
	// If we are here, it means the "youMixer/welcome" URI was requested.
	// Here, we want to return the HTML for the "content" slot of the response
	
	// Prepare some variables for illustration purposes
	$greeting = "This is my first app! Do you like it?";

	// Render a view and return it:
	return Pie::view('youMixer/content/welcome.php', compact('greeting'));
}

If you refresh your app's URL in the browser, you will now stop seeing the exception dump, but you will see a note that says "Missing view youMixer/content/welcome.php". That is because we haven't created that view yet. Let's do that now:

1. Make a new folder, APP_DIR/views/youMixer
2. In it, make a folder, content
3. In this folder, create a PHP file, welcome.php

That will be your view file. View files should be easily editable by front end designers, who may not know much about PHP development. They already have all PHP variables you passed to them (in this case, $greeting). So let's make a simple view file:

<div id="content">
	<h2>Welcome to YouMixer!></h2>
	<h3><?php echo $greeting ?></h3>
</div>

Similarly, we should create a view file for the "dashboard". Create a file at APP_DIR/views/youMixer/dashboard.php, and fill it with this HTML:

<div id="dashboard">
	<h1>YouMixer - <?php echo $slogan ?></h1>
</div>

Finally, copy the layout folder from views/myApp to views/youMixer. You are going to need the HTML layout to render the output.

That's it! Refresh your browser and if everything went well, you should now be able to see your very first action. According to the routes you've set up, your app's base URL routes to the "$app/welcome" URI.

Now, try repeating these steps to create another action called "contact" instead of welcome. You can access it using a URL like:

http://yourdomain.com/yourApp/contact

And that, my friends, is how you start making a new app with PIE. You may be wondering why each action has its own folder. Later on in the guide, you will learn that your application can handle other events besides "pie/response", which is what we did here. They include "pie/validate" and so on. To handle those, you will create files such as APP_DIR/handlers/youMixer/welcome/validate.php. This way, all the event handlers for a particular action will be grouped together under one folder.

It is a good idea to also handle the "youMixer/notFound" URI, which results any time a URL does not route to anything, or the action is not implemented yet. (For example, "youMixer/welcome" and "youMixer/contact" are now implemented, but "youMixer/whatsUp" is not). The handler should set a 404 code and output some consolation document to the browser. Feel free to take a look at myApp's handler and view for the "notFound" action, and then roll your own.

Setting up web/plugins

We are almost done setting up our app, but there is still one more thing to do. Your app is probably using plugins, which you can see referenced in the config file under pie/plugins. Plugins often provide files that need to be served to the web (such as .js, .css, and image files).

For each of these plugins, we will have to serve its web directory to the web under the following URL:

http://yourdomain.com/yourApp/plugins/$plugin_name/

where we are assuming your app's base URL was http://yourdomain.com/yourApp and $plugin_name is the name of the plugin.

Let's do this for the users and items plugins that your app includes out of the box. You can do that in two ways:

• The first way is to use symbolic links. This way does not work on Windows.

  cd APP_DIR/web/plugins
  ln -s PIE_DIR/plugins/users/web users
  ln -s PIE_DIR/plugins/items/web items

• The second way is to create an Alias directive for your webserver, and point the URLs to the correct directories, which are shown above.

Version control

You are now ready to check your project into version control. Remember not to add the $app/local folder to version control, as that will cause other developers to overwrite their $app/local folders when when updating from the repository. Also remember not to add the symbolic links you set up under APP_DIR/web/plugins (if you did), since those also depend on where you installed PIE_DIR on your system.

Before checking into version control, you will probably want to remove the $app/handlers/myApp and $app/views/myApp directories. Although you could check them into version control, you won't be using them anymore. They were just for illustration purposes.