Skip to content

Commit d1f549f

Browse files
praveen-gargpraveen-garg
authored
Merge pull request nerdapplabs#20 from aksinha-nerdapplabs/readme
Readme
2 parents 5c46270 + f5d8477 commit d1f549f

File tree

1 file changed

+110
-80
lines changed

1 file changed

+110
-80
lines changed

‎README.md‎

Lines changed: 110 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
1+
# authOauth
12

2-
# actively maintained at https://github.com/aksinha-nerdapplabs/authOauth
3+
### actively maintained at https://github.com/aksinha-nerdapplabs/authOauth
34

4-
# A Symfony2 oAuth based RESTful API Project including Web UI with FOSUserBundle + FOSRestBundle + FOSOauthServerBundle for Mobile and Web Clients
5+
**A Sample Symfony 2 RESTful API Project with FOSUserBundle + FOSRestBundle + FOSOauthServerBundle for Mobile and Web Clients.**
56

6-
This is an example project, ready to use. This project is using below Symfony Bundles:
7+
This is an example project, ready to use, based upon **Symfony 2.8** but can be easily adapted to higher Symfony versions. This project is using below Symfony Bundles:
78

89
* [FOSUserBundle](https://github.com/FriendsOfSymfony/FOSUserBundle)
910
* [FOSRestBundle](https://github.com/FriendsOfSymfony/FOSRestBundle)
@@ -15,49 +16,54 @@ This is an example project, ready to use. This project is using below Symfony Bu
1516
The salient features of this Project are:
1617
* This project consists of **API (currently, user management only) for Frontend consumption, via iPhone and Android Mobiles**, and an **administrative web based Backend system**.
1718
* The APIs and the Backend system are **internationalization enabled**. Project currently supports English, French and Hindi but can be easily extended to include other languages.
18-
* This project implements FOSRestBundle **API versioing system** via custom header "X-Accept-Version". Currently, the running API version is 1.0.
19+
* This project implements FOSRestBundle **API versioing system** via custom header **"X-Accept-Version"**. Currently, the running API version is 1.0.
1920
* **Backend theming can easily be customized and extended**. Options have been provided to pick desired front-end theme for the Backend. The choices available are - Bootstrap, Materialize and Skeleton. **To change the theme, modify key "fronend_theme" in parameters.yml accordingly.** However, the design is open-ended and you may add your preferred theme easily. Please also note that theming has only been provided for base and nav. Other top level stuff is using bootstrap, you can theme as per your choice using base theme.
2021
* The Web user management pages are coming directly from FOSUserBundle views. You may override these pages, per your need.
2122

22-
## Installation Steps:
23-
24-
**Step 0:**
25-
26-
Below environment is required:
27-
Linux
28-
=====
29-
- PHP 5.6
30-
- MySql (though other DB can also be used with a little change in the configuration)
31-
- Apache2 (alternatively, local PHP dev server can also be used for testing purpose)
32-
- Composer
33-
- Chrome browser with Postman plugin or separate Postman installation to test the API (though API can also be tested via "curl" command)
34-
35-
Windows
36-
=======
37-
- MAMP
38-
- Composer
39-
- Chrome browser with Postman plugin or separate Postman installation to test the API (though API can also be tested via "curl" command)
40-
41-
Mac
42-
===
43-
- MAMP
44-
- Composer
45-
- Chrome browser with Postman plugin or separate Postman installation to test the API (though API can also be tested via "curl" command)
23+
# Table of Contents
24+
* [Requirements](#requirements)
25+
* [Installation](#installation)
26+
* [Configuring Apache2](#configure-apache2)
27+
* [Using the Package](#using-this-package)
28+
* [Roadmap](#roadmap)
29+
* [Change Logs](#change-logs)
30+
* [Contribution Guidelines](#contribution-guidelines)
31+
32+
# <a name="requirements"></a>Requirements
33+
34+
Below environment is required:
35+
36+
* Linux
37+
- PHP 5.6
38+
- MySql (though other DB can also be used with a little change in the configuration)
39+
- Apache2 (alternatively, local PHP dev server can also be used for testing purpose)
40+
- Composer
41+
- Chrome browser with Postman plugin or separate Postman installation to test the API (though API can also be tested via "curl" command)
42+
* Windows
43+
- MAMP
44+
- Composer
45+
- Chrome browser with Postman plugin or separate Postman installation to test the API (though API can also be tested via "curl" command)
46+
* Mac
47+
- MAMP
48+
- Composer
49+
- Chrome browser with Postman plugin or separate Postman installation to test the API (though API can also be tested via "curl" command)
4650

4751
***Note regarding Webserver:***
4852

49-
As this project uses OAuth2 server, for smooth results, Apache webserver is highly recommended. You may want to create a site, say http://auth.dev, for it. Please refere to section **"Configuring Apache"** below for an example implementation.
53+
As this project uses OAuth2 server, for smooth results, Apache webserver is highly recommended. You may want to create a site, say http://auth.dev, for it. Please refere to section [Configuring Apache2](#configure-apache2) below for an example implementation.
54+
55+
*However, if you wish to use php local dev server, you will need to start two instances of php local dev server at __two different ports (say 8000 and 8080)__ in two separate terminal windows/tabs, section [Using the Package](#using-this-package), and replace oauth urls accordingly in Step 2 below. This is necessary as php local dev server is a simple single threaded web server and oAuth server needs to work on more than one process simultaneously. Using a single local dev server severly hampers this and blocks execution.*
5056

51-
However, if you wish to use php local dev server, you will need to start two instances of php local dev server at two different ports (say 8000 and 8080) in two separate terminal windows/tabs, section **"Use this Package"**, and replace oauth urls accordingly in Step 2 below. This is necessary as php local dev server is a simple single threaded web server and oAuth server needs to work on more than one process simultaneously. Using a single local dev server severly hampers this and blocks execution.
57+
# <a name="installation"></a>Installation
5258

5359
**Step 1 - Clone the project:**
5460

5561
Git clone this project from Github to a web folder, say auth, via
56-
git clone .... auth
62+
$ git clone .... auth
5763

5864
and run
59-
cd /path/to/auth
60-
composer install
65+
$ cd /path/to/auth
66+
$ composer install
6167

6268
**Step 2 - Replace parameter values in parameters.yml**
6369

@@ -79,28 +85,28 @@ However, if you wish to use php local dev server, you will need to start two ins
7985

8086
**Step 3 - Create Database tables**
8187

82-
cd /path/to/auth
83-
php app/console doctrine:database:create
84-
php app/console doctrine:schema:create
88+
$ cd /path/to/auth
89+
$ php app/console doctrine:database:create
90+
$ php app/console doctrine:schema:create
8591

8692
**Step 4 - Create assets**
8793

88-
cd /path/to/auth
89-
php app/console assets:install
90-
php app/console assetic:dump
94+
$ cd /path/to/auth
95+
$ php app/console assets:install
96+
$ php app/console assetic:dump
9197

9298
**Step 5 - Create an Admin user**
9399

94-
cd /path/to/auth
95-
php app/console fos:user:create admin [email protected] password
100+
$ cd /path/to/auth
101+
$ php app/console fos:user:create admin [email protected] password
96102

97103
Make this user admin
98104

99-
php app/console fos:user:promote admin ROLE_ADMIN
105+
$ php app/console fos:user:promote admin ROLE_ADMIN
100106

101107
Now you are ready to use the Package!
102108

103-
## Configure Apache2
109+
# <a name="configure-apache2"></a>Configuring Apache2
104110

105111
Execute below commands which are specific to Apache2 configuration on Ubuntu 16.04. However, for rest of the env, the detail are quite similar.
106112

@@ -114,37 +120,37 @@ $ sudo cp sites-available/000-default.conf sites-available/auth.conf
114120
Via an editor, as superuser, copy/paste below section to sites-available/auth.conf:
115121

116122
```
117-
<VirtualHost *:80>
118-
# The ServerName directive sets the request scheme, hostname and port that
119-
# the server uses to identify itself. This is used when creating
120-
# redirection URLs. In the context of virtual hosts, the ServerName
121-
# specifies what hostname must appear in the request's Host: header to
122-
# match this virtual host. For the default virtual host (this file) this
123-
# value is not decisive as it is used as a last resort host regardless.
124-
# However, you must set it for any further virtual host explicitly.
125-
ServerName auth.dev
126-
127-
ServerAdmin webmaster@localhost
128-
DocumentRoot /var/www/html/authOauth/web
129-
130-
# Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
131-
# error, crit, alert, emerg.
132-
# It is also possible to configure the loglevel for particular
133-
# modules, e.g.
134-
#LogLevel info ssl:warn
135-
136-
ErrorLog ${APACHE_LOG_DIR}/error.log
137-
CustomLog ${APACHE_LOG_DIR}/access.log combined
138-
139-
# For most configuration files from conf-available/, which are
140-
# enabled or disabled at a global level, it is possible to
141-
# include a line for only one particular virtual host. For example the
142-
# following line enables the CGI configuration for this host only
143-
# after it has been globally disabled with "a2disconf".
144-
#Include conf-available/serve-cgi-bin.conf
145-
</VirtualHost>
146-
147-
# vim: syntax=apache ts=4 sw=4 sts=4 sr noet
123+
<VirtualHost *:80>
124+
# The ServerName directive sets the request scheme, hostname and port that
125+
# the server uses to identify itself. This is used when creating
126+
# redirection URLs. In the context of virtual hosts, the ServerName
127+
# specifies what hostname must appear in the request's Host: header to
128+
# match this virtual host. For the default virtual host (this file) this
129+
# value is not decisive as it is used as a last resort host regardless.
130+
# However, you must set it for any further virtual host explicitly.
131+
ServerName auth.dev
132+
133+
ServerAdmin webmaster@localhost
134+
DocumentRoot /var/www/html/authOauth/web
135+
136+
# Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
137+
# error, crit, alert, emerg.
138+
# It is also possible to configure the loglevel for particular
139+
# modules, e.g.
140+
#LogLevel info ssl:warn
141+
142+
ErrorLog ${APACHE_LOG_DIR}/error.log
143+
CustomLog ${APACHE_LOG_DIR}/access.log combined
144+
145+
# For most configuration files from conf-available/, which are
146+
# enabled or disabled at a global level, it is possible to
147+
# include a line for only one particular virtual host. For example the
148+
# following line enables the CGI configuration for this host only
149+
# after it has been globally disabled with "a2disconf".
150+
#Include conf-available/serve-cgi-bin.conf
151+
</VirtualHost>
152+
153+
# vim: syntax=apache ts=4 sw=4 sts=4 sr noet
148154
```
149155

150156
Via an editor, as superuser, modify /etc/hosts to include below line:
@@ -171,14 +177,16 @@ $ sudo setfacl -dR -m u:www-data app/cache app/logs
171177
$ sudo chmod -R ogu+rwx app/cache app/logs web
172178
```
173179

174-
## Use this Package
180+
# <a name="using-the-package"></a>Use the Package
175181

176182
1. Test API
177183
2. Use API via a Mobile Client
178184
3. Backend Administration
179-
4. Troubleshooting
180185

181-
If you are using php local dev server, please start the server at two different ports (say 8000 and 8080) in two terminal windows as below:
186+
```
187+
Please refer to **Note regarding webserver** in [Requirements](#requirements) section.
188+
If you are using php local dev server, please start the server at two different ports
189+
(say 8000 and 8080) in two terminal windows as below:
182190
183191
In first terminal window,
184192
@@ -190,9 +198,12 @@ In second terminal window,
190198
cd /path/to/auth
191199
php app/console server:run 127.0.0.1:8080
192200
193-
You may also need to configure parameters.yml accordingly. Then in a browser, you may use http://127.0.0.1:8000 to run this package.
201+
You may also need to configure parameters.yml accordingly. Then in a browser, you may use
202+
http://127.0.0.1:8000 to run this package.
194203
195-
Alternatively, if you have successfully configured Apache2, then modify parameters.yml accordingly can start using the package vide say, http://auth.dev.
204+
Alternatively, if you have successfully configured Apache2, then modify parameters.yml
205+
accordingly can start using the package vide say, http://auth.dev.
206+
```
196207

197208
#### 1. Test API
198209

@@ -217,7 +228,7 @@ Android: https://github.com/mshariq-nerd/MSOAuth2
217228

218229
In a browser, goto the package site by http://127.0.0.1:8000. This is the Backend Administration tool and can be plugged into any User App easily. It is a simple page. The options are self explanatory.
219230

220-
#### 4. Troubleshooting
231+
# <a name="troubleshooting"></a>Troubleshooting
221232

222233
Sometimes, you may run into permission issues. You may try below commands, single or in combination:
223234

@@ -230,3 +241,22 @@ $ sudo rm -rf app/cache/* app/logs/*
230241
231242
$ sudo chmod -R ogu+rwx app/cache app/logs web
232243
```
244+
245+
# <a name="roadmap"></a>Roadmap
246+
247+
Here's the TODO list for the next release (**2.0**).
248+
249+
* [ ] Refactoring the UserController to have a single UserController instead of two separate UserControllers for admin and regular user.
250+
* [ ] Refactoring the UserController to use API from AuthController instead using FOSUserBundle so that CRUD comes from a single source.
251+
* [ ] Add provision for admin to reset password for a user.
252+
253+
254+
# <a name="change-logs"></a>Change Logs
255+
256+
257+
258+
# <a name="contribution-guidelines"></a>Contribution Guidelines
259+
260+
Support follows PSR-2 PHP coding standards, and semantic versioning.
261+
262+
Please report any issue you find in the issues page.

0 commit comments

Comments
 (0)