ClubMaster
==========
:Author:    Michael Holm Kristensen
:Email:     <hollo@hollo.dk>
:Date:      2012-10-20
:Revision:  27


Feedback
--------
It would really help me a lot of you can give me just any feedback at hollo@hollo.dk.


Prerequirements
---------------
In order to run this software you need to following prerequirements:

- Webserver
- PHP 5.3.2
- MySQL 5

Besides it higly suggested to:

- Enable mod_rewrite for apache
- AllowOverride All in your apache configuration


Installation
------------
In order to install ClubMaster, do the following:

- Extract files to your server
- Create the database
- Locate the web/setup.php folder in your browser, and follow onscreen installation


Upgrade
-------
To upgrade from a previously version of ClubMaster, do the following:

- Backup the database
- Backup the old files
- Extract the new project in top of the old
- Visit the page /upgrade, and follow the onscreen information

[NOTE]
In version 1.2 we will introduce a new way of migration that will go much easier than before, unfortunately that will result in no way to upgrade from version 1.1 to 1.2.


Configuration
-------------
In app/config/clubmaster.yml if will find a config file, where you can change almost anything in the system.

You can enable and disable different modules, you should take a look at this file in order to fit ClubMaster to your needs.


Mail Templating
---------------
The system will send mails out at different events. The filenames should explain pretty good when the mail is sent out.

You can find all the templates in:

src/Club/MailBundle/Resources/views/Template/

If you want to change any of the context of the default messages ClubMaster send out, you should make a copy of the folder to:

app/Resources/ClubMailBundle/views/Template/

Just give the files the exact same name, and you can do whatever you like with the messages.


Development
-----------
If you want to support the system and help developing it, you are so welcome. All you have to know about getting started with development can you read about in this section.

First of all, ClubMaster is written in Symfony2, you can read all about the framework on www.symfony.com, its a great PHP framework to ease development of PHP projects. Take a good look at the framework before you go any further, that is a really important step.

Afterwards, if you just want to get up and running in a development environment all you have to do is:


Fork on GitHub
~~~~~~~~~~~~~~
Make a fork of our project on GitHub, https://www.github.com/clubmaster/clubmaster.

Follow the help provided by github.


Get dependencies
~~~~~~~~~~~~~~~~
ClubMaster uses the composer to get all dependencies, you can read more about that on getcomposer.org.

Getting the composer enter the following command:

$ curl -s https://getcomposer.org/installer | php

Now you have the composer, install the dependencies:

$ ./composer.phar install


Configure database
~~~~~~~~~~~~~~~~~~
Edit the file app/config/parameters.yml to fit your needs.


Initial test data
~~~~~~~~~~~~~~~~~
I have made a shell script to prepare the database schema, and load some test data. Just run the following script and see the onscreen magic :)

./bin/remake_schema.sh


Initial graphics
~~~~~~~~~~~~~~~~
If you for some reason has problem with the above script, you has to run the following just to init the graphics except and prepare the setup for the installer.

php app/console assets:install
php app/console doctrine:database:create


Start coding
~~~~~~~~~~~~
When you are developing in Symfony2 there are multiple environmens:

Production where you have enabled all the cache, and everything is optimized for optimal performance.

Development where you have disabled a lot of caching, and get a nice web debugging tool to see what you application does behind the scene.

To load the different environments go the the one url or the other:

Production:
http://localhost/clubmaster/web/app.php

Development:
http://localhost/clubmaster/web/app_dev.php


Login
~~~~~
As in the demo project, just log in with:

Administrator user:
username: 1
password: 1234

Normal user:
username: 10
password: 1234


API
---
We have developed an API which is open for everyone. However the API has some limitations what security is conserned. Some functions is locked with basic access authentication other functions is locked with an API key. More about that under each function section.

The API key is a value defined in the application in the file:

/app/config/clubmaster.yml

Then you have to use the API key, simply set a header values in your request, API_KEY and with the value of the API key.


Here is 2 different usages of the API, first we will fetch all users afterwards we will attend an event.

When you want to fetch all users, we dont want this method to be public so thats why you have to use the API key, watch this curl example.

curl -H "API_KEY:YOUR_KEY" http://example.com/api/users/

If you want to attend an event, you dont get access to any sensitive data, so you dont have to apply the API key, simple do a basic access authentication before the login with the users credentials.

curl -u "user:password" http://example.com/api/events/{id}/attend

That pretty much all you need to know before you can use our API.

Date format
~~~~~~~~~~~
Date format will always be transmitted in ISO 8601 format.

You can read about it here:

http://en.wikipedia.org/wiki/ISO_8601


Validate authentication
~~~~~~~~~~~~~~~~~~~~~~~
URL: /api/auth
Method: ANY

Success response will be HTTP response code 200, and a json response with specified user
Failure response will be HTTP response code 403


Get all events
~~~~~~~~~~~~~~
URL: /api/events/
Method: GET

Success response will be HTTP response code 200, and a json response with all events


Attend event
~~~~~~~~~~~~
URL: /api/events/{id}/attend
Method: POST

Use basic access authentication for the user who has to authenticate.
Success response will be HTTP response code 200


Unattend event
~~~~~~~~~~~~~~
URL: /api/events/{id}/unattend
Method: POST

Use basic access authentication for the user who has to authenticate.
Success response will be HTTP response code 200


Get all users
~~~~~~~~~~~~~
URL: /api/users/
Method: GET
Header: API_KEY

Success response will be HTTP response code 200, and a json response with all users


Get user
~~~~~~~~
URL: /api/users/{id}
Method: GET
Header: API_KEY

Success response will be HTTP response code 200, and a json response with specified user


Get users events
~~~~~~~~~~~~~~~~
URL: /api/users/events/
URL: /api/users/events/{start}
URL: /api/users/events/{start}/{end}
Method: GET

Parameters:
{start}: 2011-01-01
{end}: 2011-01-02

Success response will be HTTP response code 200, and a json response with all events


Get all teams
~~~~~~~~~~~~~
URL: /api/teams/
URL: /api/teams/{start}
URL: /api/teams/{start}/{end}
Method: GET

Parameters:
{start}: 2011-01-01
{end}: 2011-01-02

Success response will be HTTP response code 200, and a json response with all teams


Get users teams
~~~~~~~~~~~~~~~
URL: /api/users/teams/
URL: /api/users/teams/{start}
URL: /api/users/teams/{start}/{end}
Method: GET

Parameters:
{start}: 2011-01-01
{end}: 2011-01-02

Success response will be HTTP response code 200, and a json response with all teams


Attend team
~~~~~~~~~~~
URL: /api/teams/{id}/attend
Method: POST

Use basic access authentication for the user who has to authenticate.
Success response will be HTTP response code 200


Unattend team
~~~~~~~~~~~~~
URL: /api/teams/{id}/unattend
Method: POST

Use basic access authentication for the user who has to authenticate.
Success response will be HTTP response code 200


Participant team
~~~~~~~~~~~~~~~~
URL: /api/teams/participant
Method: ANY
Header: API_KEY

Use basic access authentication for the user who has to authenticate.
Success response will be HTTP response code 200


Get locations
~~~~~~~~~~~~~
URL: /api/locations/
Method: GET

Success response will be HTTP response code 200, and a json response with all locations


Get fields
~~~~~~~~~~
URL: /api/fields/{location_id}
URL: /api/fields/{location_id}/{date}
Method: GET

Parameters:
{date}: 2011-01-01

Success response will be HTTP response code 200, and a json response with all fields in a location


Get fields modified
~~~~~~~~~~~~~~~~~~~
URL: /api/fields/
Method: GET

Success response will be HTTP response code 200, and a json response with all fields with latest modified time


Get bookings
~~~~~~~~~~~~
URL: /api/bookings/{location_id}
URL: /api/bookings/{location_id}/{date}
Method: GET

Parameters:
{date}: 2011-01-01

Success response will be HTTP response code 200, and a json response with all used intervals


Make booking
~~~~~~~~~~~~
URL: /api/bookings/book/{date}/{interval_id}/{user_id}
URL: /api/bookings/book/{date}/{interval_id}/guest
Method: POST

Parameters:
{date}: 2011-01-01

Use basic access authentication for the user who has to authenticate.
Success response will be HTTP response code 200 and json response with booking object


Cancel booking
~~~~~~~~~~~~~~
URL: /api/bookings/cancel/{id}
Method: POST

Use basic access authentication for the user who has to authenticate.
Success response will be HTTP response code 200