Someline Starter PHP Framework
Tested and used in production by Someline Inc.
Someline Starter is a PHP framework for quick building Web Apps and Restful APIs, with modern design pattern foundation.
It is built on top of popular
Laravel 5.8 framework,
Unit Tests, isolated front-end and back-end layer.
Someline Starter is born for 3 reasons:
Quick web application starter without the need to build from scratch using Laravel.
Isolated front-end and back-end layer using Restful API.
Introducing modern design pattern, which have a better foundation when starting, for PHP projects.
See In Action
Frontend with Vue.js and displaying data via Restful API
See In Video
Watch the video tutorial from below.
Someline Starter is suitable for Restful API oriented projects.
The Restful APIs as a backend layer which provide simple unified interfaces for frontend: Web and Mobile apps.
It utilized Laravel Passport to authenticate protected resources.
It also provides Unit Tests for API testing and framework testing.
It is shipped with Angulr Theme and features in every part that you can easily reference.
It is fully utilised Repository Design pattern.
If you are not familiar with any of these packages, you are recommended to get to know them as they are really helpful when you needed.
- Laravel 5.8 laravel/framework
- Laravel IDE Helper barryvdh/laravel-ide-helper
- Clockwork itsgoingd/clockwork
- Laravel 5 log viewer rap2hpoutre/laravel-log-viewer
- Restful API dingo/api
- L5 Repository prettus/l5-repository
- Fractal thephpleague/fractal
- Laravel Validation prettus/laravel-validation
- Intervention Image intervention/image
- Intervention Image Cache intervention/imagecache
- Rest API Client someline/rest-api-client
- Someline Image Service someline/someline-image
- Laravel Passport laravel/passport
Please buy a license if you use this in your project.
- Vue.js Reactive Components for Modern Web Interfaces
Make sure you have already installed PHP 7.1 and composer.
You can get started either option A or B:
A. Get started via composer
Under working folder, run the command:
composer create-project --prefer-dist someline/someline-starter someline-starter
A.1. Add to a git repository (When Needed)
https://github.com/username/repository-name.git to your own git repository address.
cd someline-starter git init git add . git commit -m 'Initial commit' git remote add origin https://github.com/username/repository-name.git git push -u origin master
B. Get started via cloning repository
Clone this project to your working folder and open the directory:
git clone https://github.com/someline/someline-starter
B.1. Add to a git repository (When Needed)
https://github.com/username/repository-name.git to your own git repository address.
cd someline-starter rm -rf .git git init git add . git commit -m 'Initial commit' git remote add origin https://github.com/username/repository-name.git git push -u origin master
- PHP: >=7.1.8
- MySQL: >=5.7
- SQLite extension
- Laravel 5: https://laravel.com/docs/5.8/installation
- Yarn: https://yarnpkg.com/
- NodeJS: https://nodejs.org/
- Bower: https://bower.io/
someline-starter folder (Optional, run only when you are not inside the project root folder)
All these commands should be executed under the root of someline-starter project
Install composer dependencies
Install npm dependencies using Yarn dependency management (suggested)
Note: This command should be outside homestead environment. Also, you can still use
npm install if you want.
Install bower dependencies
Set-up Laravel, after these commands, please change
.env file for your own environment settings
sudo cp .env.example .env sudo chmod -R 777 storage bootstrap/cache php artisan key:generate
Database & Seeding
You need to create a Database e.g.
someline_starter with Encoding
utf8mb4 and Collation
CREATE DATABASE `someline_starter` DEFAULT CHARACTER SET = `utf8mb4` DEFAULT COLLATE = `utf8mb4_unicode_ci`;
Change database config in
.env file to the match the database that your just created.
After having database configuration setup, you can now do migrations and seeding.
php artisan migrate php artisan db:seed
Install Laravel Passport with encryption keys to generate secure access tokens.
php artisan passport:install
When deploy in server:
sudo chown www-data:www-data storage/oauth-*.key sudo chmod 600 storage/oauth-*.key
Ready to go
Until this point, you should be able to visit the home page.
For example, if you have set the domain:
Just visit: http://someline-starter.sl/
It should prompt you for login, use:
You are free to change the seeding account information from the file:
You are done. Yeah!
Explore and start to build on top of it.
Development Process and Flow
You will need to know, read and understand fowllowing before you can start build on top of these.
- Laravel Docs
- Restful API Best Practise
- dingo/api Guide
- Repository Pattern
- Repository Usage
- Vue.js Guide
We recommend use PHPStorm IDE to build and develop your projects.
The default namespace for
app/ folder is
It is NOT recommended to change the namespace, if you are not familiar with namespace of Someline Starter as the
Someline namespace is used heavily within whole project.
However, you can still change it if you know how what you are doing, because some namespaces required manually changing.
To change namespace to your preference:
php artisan app:namespace YourApp
In order to utilize all features provided by Someline Starter, you should extended the Class from BaseClass (if there has one), e.g.
All models are located under
User Model under folder
app/Models/Foundation/ is created by default with primary key
user_id, you should not change this class heavily because it is used almost everywhere within whole project. You can use global function
auth_user() to access currently logged in user.
Every model should extend
Someline/Models/BaseModel which has a observer
Someline/Observers/BaseModelObserver that you can utilize all model events within the Model, e.g.
When creating new model, you should do it using command to auto generate related Repository classes.
php artisan starter:entity Post
All Web related files are located under
Web Routes are defined in file
Web Controllers are defined in folder
All API related files are located under
API Routes are defined in file
API Controllers are defined in folder
When you create APIs, you need to test them before you can use it. You should test all APIs using Unit Tests provided or create new Unit Tests. Not recommended to test using Browser or Postman, etc.
All repository related files are located under
app/ with specific types as parent folders.
Angulr Styles and Scripts:
Angulr with Blade views:
When made changes in scripts, styles, you will need to run the command.
In development, run:
yarn run dev
In development and watching assets for changes, run:
yarn run watch
In production, run:
yarn run production
When you changed theme files, run:
yarn run theme
API and Unit Tests
You may need to change the
local service configs under
dev environment from
config/rest-client.php to fit your local development configurations.
Also change the value of
.env file to the
secret value of
Password Grant Client record in
API Unit Tests:
Debug and Clockwork
View all requests and request information from file
OAuth Web Support
OAuth HTTP URL:
Web Log Viewer
Log Viewer HTTP URL:
We recommend to use migrations for database structure and seeding.
Directly changing from database or not follow migrations is strongly NOT recommended.
Flow of creating database migrations:
Create a migration file (Auto generated when use
php artisan starter:entity), under folder
Add essential columns to migration file (Auto generated when use
php artisan starter:entity):
You are recommended to use
tablename_id format as primary incremental key, for example, for table
posts, you need to use
post_id, and when this become a foreign key, you should keep the same name in other table
You are also recommended to use the
user_id field in all tables, for example, use
user_id as staff id instead of
company_staffs table. If there are no meaning for
user_id in certain tables, you should still put
user_id field in case for future usage. So, you need to use it smartly to fit your table scenarios accordingly. And, similarly, you may optionally want to add a
related_user_id field to indicate certain record is related to a user depends on your own needs.
The following columns are always required by
$table->unsignedInteger('user_id')->index(); $table->unsignedInteger('created_by')->nullable(); $table->timestamp('created_at')->nullable(); $table->ipAddress('created_ip')->nullable(); $table->unsignedInteger('updated_by')->nullable(); $table->timestamp('updated_at')->nullable(); $table->ipAddress('updated_ip')->nullable();
And remove timestamps():
Finally, the table blue print should be looks like, e.g. in
$table->increments('post_id'); $table->unsignedInteger('user_id')->index(); // Adding more table related fields here... $table->unsignedInteger('created_by')->nullable(); $table->timestamp('created_at')->nullable(); $table->ipAddress('created_ip')->nullable(); $table->unsignedInteger('updated_by')->nullable(); $table->timestamp('updated_at')->nullable(); $table->ipAddress('updated_ip')->nullable();
Add factory support, under file
Create seeding support, under folder
Refresh Database Migrations and Seeding
When you added or changed to migrations or seeds files, or you just simply want to refresh everything in database:
php artisan migrate:refresh --seed
The Someline Starter framework is open-sourced software licensed under the MIT license.