If you have attended any hackathons in the past, then you know how much time it takes to get a project started: decide on what to build, pick a programming language, pick a web framework, pick a CSS framework. A while later, you might have an initial project up on GitHub and only then can other team members start contributing. Or how about doing something as simple as Sign in with Facebook authentication? You can spend hours on it if you are not familiar with how OAuth 2.0 works.
When I started this project, my primary focus was on simplicity and ease of use. I also tried to make it as generic and reusable as possible to cover most use cases of hackathon web apps, without being too specific. In the worst case you can use this as a learning guide for your projects, if for example you are only interested in Sign in with Google authentication and nothing else.
Laravel is a web application framework with expressive, elegant syntax. Laravel attempts to take the pain out of development by easing common tasks used in the majority of web projects, such as authentication, routing, sessions, queueing, and caching.
Laravel Hackathon Starter is a boilerplate application developed with Laravel 5.2 to keep you ahead in hackathons.
- Features
- Prerequisites
- Getting Started
- Generator
- Obtaining API Keys
- Project Structure
- List of Packages
- Useful Tools and Resources
- Recommended Design Resources
- Recommended Laravel Libraries
- Pro Tips
- FAQ
- How It Works
- Laravel Eloquent Cheatsheet
- Deployment
- Changelog
- Contributing
- License
- Local Authentication using Email and Password
- OAuth 1.0a Authentication via Twitter
- OAuth 2.0 Authentication via Facebook, Google, GitHub, LinkedIn, Instagram
- Flash notifications
- MVC Project Structure
- Bootstrap 3
- Contact Form (powered by Mailgun, Sendgrid or Mandrill)
- Account Management
- Gravatar
- Profile Details
- Change Password
- Forgot Password
- Reset Password
- Delete Account
- CSRF protection
- API Examples: Facebook, Foursquare, Last.fm, Tumblr, Twitter, Stripe, LinkedIn and more.
- [Mysql or Postgresql](https://www.mysql.com/ or http://www.postgresql.org/)
- PHP 5.4+
- Command Line Tools
Mac OS X: Xcode (or OS X 10.9+:
xcode-select --install)Windows: Visual Studio
Ubuntu /
Linux Mint:
sudo apt-get install build-essentialFedora:
sudo dnf groupinstall "Development Tools"OpenSUSE:
sudo zypper install --type pattern devel_basis
Note: If you are new to Laravel, I recommend to watch Laravel From Scratch screencast by Jeffery Way that teaches Laravel 5 from scratch. Alternatively, here is another great tutorial for building a project management app for beginners/intermediate developers - How to build a project management app in Laravel 5.
The easiest way to get started is to clone the repository:
# Get the project
git clone https://github.com/unicodeveloper/laravel-hackathon-starter.git hackathon-starter-pack
# Change directory
cd hackathon-starter-pack
# Rename env.example to .env and fill in all the keys and secrets and also generate a secure key for the app using `php artisan key:generate`
# Install Composer dependencies
composer install
# Run your migrations
php artisan migrate
# Publish the config files for the different service providers for Cloudder, Laravel Github, Slack,Twitter, Twilio by quickly checking their readme and following the steps
*[Cloudder](https://github.com/jrm2k6/cloudder)
*[Twitter](https://github.com/thujohn/twitter)
*[Twilio](https://github.com/aloha/laravel-twilio)
*[Github](https://github.com/GrahamCampbell/Laravel-GitHub)
*[Slack](https://github.com/vluzrmos/laravel-slack-api)
*[Socialite Providers](https://github.com/SocialiteProviders/Instagram)
*[Socialite LinkedIn](https://github.com/SocialiteProviders/LinkedIn)
php artisan serveTo use any of the included APIs or OAuth authentication methods, you will need to obtain appropriate credentials: Client ID, Client Secret, API Key, or Username & Password. You will need to go through each provider to generate new credentials.
Note: When you ready to deploy to production don't forget to
add your new url to Authorized Javascript origins and Authorized redirect URI,
e.g. http://my-awesome-app.herokuapp.com and
http://my-awesome-app.herokuapp.com/auth/google/callback respectively.
The same goes for other providers.
Note: After a successful sign in with Facebook, a user will be redirected back to home page with appended hash #_=_ in the URL. It is not a bug. See this Stack Overflow discussion for ways to handle it.
| Name | Description |
|---|---|
| config/app.php | Configuration for service providers and facades |
| config/auth.php | Configuration for password resets |
| config/broadcasting.php | Configuration for broadcasting |
| config/cache.php | Configuration for cache generation and storagr |
| config/cloudder.php | Configuration for cloudinary |
| config/compile.php | Configuration for compilation |
| config/database.php | Configuration for database drivers |
| config/filesystems.php | Configuration for different file systems |
| config/github.php | Configuration for github API |
| config/mail.php | Configuration for mails |
| config/queue.php | Configuration for queue |
| config/services.php | Configuration for several services like mailgun et.c |
| config/session.php | Configuration for sessions |
| config/ttwitter.php | Twitter API config file |
| config/twilio.php | Twilio API config file |
| config/view.php | Configuration for location of views and view cache |
| controllers/AccountController.php | Controller for Account management |
| controllers/AviaryController.php | Controller for Aviary API functionality |
| controllers/ClockworkController.php | Controller for Clockwork API functionality |
| controllers/ContactController.php | Controller for Contact page |
| controllers/Controller.php | BaseController |
| controllers/GithubController.php | Controller for Github API functionality |
| controllers/LastFmController.php | Controller for LastFM API functionality |
| controllers/LobController.php | Controller for Lob API functionality. |
| controllers/NytController.php | Controller for New York Times API functionality |
| controllers/OauthController.php | Controller for Oauthentication |
| controllers/PaypalController.php | Controller for Paypal API functionality |
| controllers/SteamController.php | Controller for Stream API functionality |
| controllers/StripeController.php | Controller for Stripe API functionality |
| controllers/TwilioController.php | Controller for Twilio API functionality |
| controllers/TwitterController.php | Controller for Twitter API functionality |
| controllers/WebScrapingController.php | Controller for Web Scraping. |
| controllers/YahooController.php | Controller for Yahoo API functionality |
| controllers/user.js | Controller for user account management. |
| models/User.php | Moodel for User. |
| public/ | Static assets (fonts, css, js, img). |
| public/css/main.css | Main stylesheet for your app. |
| resources/views/account/ | Templates for login, password reset, signup, profile. |
| views/api/ | Templates for API Examples. |
| views/partials/alerts.blade.php | Error, info and success flash notifications. |
| views/partials/navbar.blade.php | Navbar partial template. |
| views/layouts**/master.blade.php | Base template. |
| views/apidashboard.blade.php | API dashboard template. |
| views/contact.blade.php | Contact page template. |
| views/welcome.blade.php | Home page template. |
| .travis.yml | Travis CI integration. |
| .env.example | Your API keys, tokens, passwords and database URI. |
| composer.json | File for loading all php packages. |
| package.json | File for loading all necessary node modules. |
| artisan | File for enabling commands to run |
| Package | Description |
|---|---|
| socialite | Sign-in with Facebook, Twitter and Github |
| socialite providers | Sign-in with LinkedIn, Instagram |
| cloudder | Upload images to Cloudinary |
| laravel github | Github API library |
| clockwork | Clockwork SMS API library. |
| goutte | Scrape web pages using jQuery-style syntax. |
| laravel framework | PHP web framework |
| Twitter API library | |
| twilio | Twilio API library |
| lob-php | Lob API library |
| lastfm-api-wrapper | Lastfm API library |
| phpunit | PHP testing library |
| guzzlehttp | Simplified HTTP Request library |
- Laravel Daily - Awesome laravel tips daily
- Laravel News - Laravel and PHP tutorials.
- Goodheads - Laravel, PHP and JS tutorials
- Favicon Generator - Generate favicons for PC, Android, iOS, Windows 8.
- Code Guide - Standards for developing flexible, durable, and sustainable HTML and CSS.
- Bootsnipp - Code snippets for Bootstrap.
- UIBox - Curated HTML, CSS, JS, UI components.
- Bootstrap Zero - Free Bootstrap templates themes.
- Google Bootstrap - Google-styled theme for Bootstrap.
- Font Awesome Icons - It's already part of the Hackathon Starter, so use this page as a reference.
- Colors - A nicer color palette for the web.
- Creative Button Styles - awesome button styles.
- Creative Link Effects - Beautiful link effects in CSS.
- Medium Scroll Effect - Fade in/out header background image as you scroll.
- GeoPattern - SVG background pattern generator.
- Trianglify - SVG low-poly background pattern generator.
- laravel-medialibrary - Associated media files with your Eloquent models easily.
- laravel-emoji - For using emojis in your app
- laravel-quotes - For using all sorts of quotes especially DJKHALED in your app
You need to add the following hidden input element to your form. This has been added in the existing codebase as part of the CSRF protection.
{!! csrf_field() !!}
Chances are you haven't generated the app key, so run php artisan key:generate.
Chances are you haven't put your credentials in your .env file.
This section is intended for giving you a detailed explanation about how a particular functionality works. Maybe you are just curious about how it works, or maybe you are lost and confused while reading the code, I hope it provides some guidance to you.
Flash messages allow you to display a message at the end of the request and access it on next request and only next request. For instance, on a failed login attempt, you would display an alert with some error message, but as soon as you refresh that page or visit a different page and come back to the login page, that error message will be gone. It is only displayed once. All flash messages are available in your views via laravel sessions.
A more correct way to be to say "How do I create a new route". The main file routes.php contains all the routes.
Each route has a callback function associated with it. Sometimes you will see 3 or more arguments
to routes. In cases like that, the first argument is still a URL string, while middle arguments
are what's called middleware. Think of middleware as a door. If this door prevents you from
continuing forward, you won't get to your callback function. One such example is a route that requires authentication.
Route::get('/account', 'UserController@getAccount');It always goes from left to right. A user visits /account page. Then auth middleware
checks if you are authenticated:
Route::get('/account', [
'uses' => 'AccountController@getAccountPage',
'as' => 'account.dashboard',
'middleware' => ['auth']
]);If you are authenticated, you let this visitor pass through your "door" by calling return $next($request); in the auth middleware and if you are authenticated, you will be redirected to Account Management page, otherwise you will be redirected to Login page.
Here is a typical workflow for adding new routes to your application. Let's say we are building a page that lists all books from database.
Step 1. Start by defining a route.
Route::get('/books', 'BookController@getBooks');Step 2. Create a new model Book.php inside the app directory. You can simply run php artisan make:model Book
namespace App;
class Book
{
/**
* The attributes that are mass assignable.
*
* @var array
*/
protected $fillable = [
'name', 'isbn',
];
}Step 3. Create a migration file like so: php artisan make:migration create_books_table
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;
class CreateBooksTable extends Migration
{
/**
* Run the migrations.
*
* @return void
*/
public function up()
{
Schema::create('books', function (Blueprint $table) {
$table->increments('id');
$table->string('name');
$table->string('isbn');
$table->timestamps();
});
}
/**
* Reverse the migrations.
*
* @return void
*/
public function down()
{
Schema::drop('books');
}
}Step 4. Create a new controller file called BookController inside the app/Http/Controllers directory. You can simply run php artisan make:controller BookController
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Book;
use App\Http\Requests;
use App\Http\Controllers\Controller;
class BookController extends Controller
{
/**
* Return all data to the Stripe API dashboard
* @return mixed
*/
public function getPage()
{
$books = Book::all();
return view('api.book')->withBooks($books);
}
}Step 5. Create books.blade.php template.
@extends('layouts.master')
@section('content')
<div class="main-container">
@include('layouts.partials.alerts')
<div class="page-header">
<h2><i style="color: #f00" class="fa fa-book"></i>All Books</h2>
</div>
<ul>
@foreach ($books in $book)
<li> $book->name </li>
@endforeach
</div>
</div>
@stopThat's it!
Once you are ready to deploy your app, you will need to create an account with a cloud platform to host it. These are not the only choices, but they are my top picks. From my experience, Heroku is the easiest to get started with, deployments and custom domain support on free accounts.
Note: To install Heroku add-ons your account must be verified.
- Finally, you can now push your code to OpenShift by running
git push -f openshift master - Note: The first time you run this command, you have to pass
-f(force) flag because OpenShift creates a dummy server with the welcome page when you create a new Node.js app. Passing-fflag will override everything with your Hackathon Starter project repository. Do not rungit pullas it will create unnecessary merge conflicts. - And you are done!
- Login to Windows Azure Management Portal
- Click the + NEW button on the bottom left of the portal
- Click COMPUTE, then WEB APP, then QUICK CREATE
- Enter a name for URL and select the datacenter REGION for your web site
- Click on CREATE WEB APP button
- Once the web site status changes to Running, click on the name of the web site to access the Dashboard
- At the bottom right of the Quickstart page, select Set up a deployment from source control
- Select Local Git repository from the list, and then click the arrow
- To enable Git publishing, Azure will ask you to create a user name and password
- Once the Git repository is ready, you will be presented with a GIT URL
- Inside your Hackathon Starter directory, run
git remote add azure [Azure Git URL] - To push your changes simply run
git push azure master - Note: You will be prompted for the password you created earlier
- On Deployments tab of your Windows Azure Web App, you will see the deployment history
Note: Alternative directions, including how to setup the project with a DevOps pipeline are available at http://ibm.biz/hackstart. A longer version of these instructions with screenshots is available at http://ibm.biz/hackstart2. Also, be sure to check out the Jump-start your hackathon efforts with DevOps Services and Bluemix video.
Thank you for considering contributing to Laravel Hackathon Starter. The contribution guide can be found in the Contribution File
If you discover a security vulnerability within Laravel Hackathon Starter, please send an e-mail to Prosper Otemuyiwa at prosperotemuyiwa@gmail.com. All security vulnerabilities will be promptly addressed.
Why not star the github repo? I'd love the attention! Why not share the link for this repository on Twitter or HackerNews? Spread the word!
Don't forget to follow me on twitter!
Thanks! Prosper Otemuyiwa.
The MIT License (MIT). Please see License File for more information.