README

Scorpio Framework for PHP -- README
-----------------------------------------------------------------------

This README file is a work in progress and contains just the basics
until a more full featured file can be created. This is here to keep in
the spirit of the "release early, release often" mentality.
Documentation is constantly being added to on the main website.

This file is formatted for Unix line endings and a 72 character width.


=== Introduction ===

What is Scorpio?

Scorpio is a PHP5 framework / component system, designed to be
light-weight and easy to use. It is similar to ezComponents or Zend
Framework. It provides enough to get you started and a pre-built admin
system for handling the most common chores. You do not have to use
those components, though they do make life a lot easier.

There is a simple CLI system for tools and applications and a web
interpretation of the MVC design pattern (you can argue if it is a true
MVC system if you like, to me it's an MVC system). The MVC layer is
fully ajax aware and uses xaJax to power it. The default template
engine is Smarty but a pure PHP engine is included. Any other template
engine can be used by creating an adaptor.


What isn't Scorpio?

Ready to use! Scorpio is not an "out-of-the-box" system. It is not a
Swiss-Army knife, jack of all trades. That is NOT the goal of this
project. It provides a consistent set of base library packages that can
help speed the development of web application development. Similarly
Scorpio is NOT like Symfony; while it has some tools for building
objects and MVC components, you must have an understanding of how the
system works before you will get the most out of them. There is nothing
to stop you using an ORM system such as Propel if you like though.


Where can I find more?

Official project home: http://scorpio.madagasgar.com/
SourceForge: http://sourceforge.net/projects/scorpiofwork


=== Requirements ===

To develop with Scorpio you will need:

* PHP 5.2+
* PDO including SQLite and MySQL for the built-in DAO objects
* GD (for captcha controller / image manipulation)
* MySQL 4.1+ (preferably 5+ for the supplied DB schemas)
* Apache 2+ (not tested with other web servers, requires mod_rewrite)
* PHP CLI for CLI (or CGI can be used but is not recommended)
* PHP POSIX / PCNTL extensions for daemon / signal handling


=== Installation ===

Extract all files to a working folder or checkout / export from the
latest stable release from SVN.

Create a config.xml file /libraries. This is the master config file
and should set-up your default database details, your details etc.
A sample config file is included to get you started.

Scorpio can use 3 separate database user accounts depending on the type
of process PHP is running as. This helps you identify the different
requests in the process list. userWeb is for web scripts (those
run under mod_php), userScript is used when running in CGI mode (either
under Apache or on the CLI) and userDaemon is used in daemon processes.

Some of the built-in components require MySQL database(s) to function.
These components are:
  * wurfl
  * dbUpdate
  * systemLogDatabase
  
These components will need config database options created for:
wurfl, system and logging. They can all be in the same database
(not recommended) and initialisation SQL scripts can be found in the
/data/sql folder.

Finally, on production system set the permissions as low as
possible to protect the config file.

---If using the built-in MVC layer---
Configure your web server; these instructions are for Apache 2.2.+
consult your web servers help files for others:

Enable Name Based Virtual Hosts and create a vhosts.conf file in
/etc/httpd/conf.d It should then contain the following entries:

## being virtual hosts
# default
<VirtualHost *:80>
        CustomLog logs/access.log combined
</VirtualHost>

# scorpio framework directory
<Directory /PATH/TO/Scorpio/*>
        Options Indexes FollowSymLinks
        AllowOverride All
</Directory>

# base
<VirtualHost *:80>
        DocumentRoot /PATH/TO/Scorpio/websites/base
        ServerAlias *.dev.base
        ServerName dev.base
        CustomLog logs/base.log combined
</VirtualHost>
## end of virtual hosts

Save the changes, do a configtest and then graceful restart of apache.

Create an entry in your hosts file in /etc/hosts

127.0.0.1  dev.base

Save the changes.

Go to the /websites/base folder and edit or create a .htaccess so that
it contains (the rewrite rule is split onto 2 lines for display, it
should only appear as 1 line in a .htaccess file):


RewriteEngine on
RewriteRule !(\.js|\.ico|\.gif|\.jpg|\.css|\.png|\.swf|\.htm|\.html
|robots\.txt)$ index.php


Create a folder for dev.base in the websites folder. This should
contain the config.xml and controllerMap.xml files from the base.
You need both a config.xml AND a controllerMap.xml file.

You will need to edit the config.xml file and change the parent
site option to base.

Now in a web browser try to access dev.base - if all went well you
should see a welcome page and you should be able to make requests
to /home/.

Note: if the config.xml file in libraries is removed, the system will
fail to start and issue a fatal error. An empty config.xml can be used
which will cause the system to use the defaults defined in:

/libraries/system/config/config.class.php

Part of this default configuration is to run as a production system
and to limit all error messages as much as possible.

Note: the logs and temp folders (unless you change them) will need to
be writable by the web user, and should NEVER be web accessible. On dev
systems it is safe to permission it equivalent of 0777.

When creating virtual hosts, be sure to point the path to the /base
folder and create the config.xml and controllerMap.xml files.


=== Daemons ===

Scorpio has a CLI daemon layer. This will only work on Linux / Unix
system that have the POSIX and PCNTL modules compiled in to PHP. To
run daemon processes requires root access (or permissions to change
user / group of running processes) if using different user / group to
that currently logged in. This is intended for advanced users and is
NOT safe for (nor tested in) shared hosting. It is highly likely that
if you tried to run a daemon in shared hosting you would lose your
account - you have been warned.

A logging daemon is included as an example of a daemon process. This
allows the database to be used as a holding area for log information,
and then a single process can write the files. This should be
considered for large, distributed applications where many machines may
try to write to a shared log file e.g. multiple web-servers serving the
same content with unified platform logs.

---You use this component at your own risk.---

For Windows users, patch libraries are included to prevent failures
from the extensions not being available. However: these patches always
return false or fail if called - therefore daemons will not daemonise
under a Windows CLI PHP instance.


=== Development Guides ===

Use and play around with the tools. A central scorpio.php tool is
included for building DAO objects, sites, plugins and controllers. This
replaces the previous generator.php and mvcGenerator.php scripts.
scorpio.php uses the generator classes that are driven by Smarty. The
templates can be customised as you see fit. You should not add custom
classes into the /libraries folder. This should be kept for Scorpio
framework files only. A /classes folder should be used for custom
classes.

When building custom classes, be sure to keep your autoload files
up-to-date otherwise you might suddenly get errors when objects cannot
be located. The system will automatically check in /libraries/autoload
and /classes/autoload for autoload files beginning with the classname
e.g.

systemUserGroup:
    is located in system_autoload.php in /libraries/autoload
    
myCustomClass:
    is located in my_autoload.php or mycustom_autoload.php or
    mycustomclass_autoload.php in /classes/autoload

If your class is not located, a final last ditch effort is made by
checking the path versus the class name.


=== Known Issues ===

* Logging can sometimes fail, especially when permissions are broken;
  ensure that the logs folder is set to 777 and try again. Failing that
  be sure to check the server error log for anything useful.
* Be sure that the master error.log file is world writable as any
  process can write to this in the event of a fatal error.
* Any domain will require a site entry in /websites with a minimal
  config.xml file AND a controllerMap.xml file. If either is missing,
  the site cannot start
* If there is no controllerMap.xml file; the site will not start. You
  can use a very basic /home config to get going:

  <?xml version="1.0" encoding="UTF-8" ?>
  <controllers>
      <controller name="home" />
  </controllers>

* If you get apache permissions issues on Fedora 7+ or any distribution
  using SELinux, then update your security context to allow Apache
  access to the files. Personally (and I know this is bad), I turn it
  off for dev boxes as I find SELinux too difficult to deal with when
  rapidly changing dev sites.
* While the released branches of Scorpio are considered "stable" there
  are very likely bugs. Should you find one, please report it to
  bugs (at) scorpio.madagasgar.com with subject "Scorpio Bug". Be sure
  to include the revision you are using and where you found the bug.
  Alternatively, post it in the SourceForge bug tracker.
* If deploying into shared hosting with a fixed public html folder e.g.
  /home/USERNAME/public_html/ then you need to make a few changes to
  the system:

  1) set the websites folder to be /home/USERNAME/public_html (in
     /libraries/config.xml add section: paths and then websites option)
  2) always include the /base
  3) symlink the base files and folders into /public_html (so you only
     have to keep one set current)
  4) for sub-domains, create folders as necessary, but in your admin
     panel always set the path to /base
  5) ensure that the .htaccess file is sat in /public_html
  6) when you don't want to run a site like that, add a .htaccess file
     and turn off mod_rewrite.

* This is just the basics, from here you have to build your own
  applications and databases etc.


=== License ===

Scorpio is released under the BSD Licence; however this applies ONLY to
the Scorpio files. The framework makes use of several other packages
that are covered by other licences. These are detailed in the LICENSE
file.

Of particular note for commercial use: the default themes and icons are
under a Creative Commons 2.5 Attribution license. You MUST keep the
links and notices attached to these files. You can purchase the rights
to remove the links by arrangement with each author.


Scorpio Framework for PHP (http://scorpio.madagasgar.com/)
Copyright (c) 2007-2010, Dave Redfern
All rights reserved.

This is a BSD style licence and applies to all files distributed as the
"Scorpio Framework" except where otherwise stated.
see: http://creativecommons.org/licenses/BSD/
see: http://scorpio.madagasgar.com/static/license

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

Neither the name of Scorpio Framework nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

-- That's all folks! --

Documentation generated on Wed, 22 Feb 2012 10:45:56 -0500 by phpDocumentor 1.4.3