Build a collaborative note app using Laravel

Introduction
What we'll be building
Setting up Laravel
Setting up Pusher
Installing frontend dependencies
Authenticating users
Note model and migration
Defining app routes
NotesController
Creating Our Note App Views
Create new note view
List all notes view
Edit note view
Conclusion

Introduction

In this tutorial, we'll build an online collaborative note app using Laravel and Pusher Channels. We'll be using Vue.js as our JavaScript framework. The app is going to be basic but will demonstrate the necessary features of a collaborative application since that's the focus of this tutorial.

What we'll be building

Before we get our hands busy, let's go over what we'll be building. The app will be a simple note taking app that is accessible only to authenticated users. With the app, a user can create new note, edit the note and/or share the link to the note to other users for editing. In the case of editing a note, the app will be able to keep track of the users editing a particular note, show other users realtime edits that are being made on the note and lastly notify the other users when a user saves the note.

Let's get started!

Setting up Laravel

Create a new Laravel project by opening your terminal and run the code below:

laravel new laravel-notes

Next, we need to setup our new Laravel project. First, we need to register the App\Providers\BroadcastServiceProvider. Open config/app.php and uncomment App\Providers\BroadcastServiceProvider in the providers array.

We then need to tell Laravel that we are using the Pusher driver in the .env file:

1// .env
2
3BROADCAST_DRIVER=pusher

Since we specified we want to use Pusher as our broadcasting driver, we need to install the Pusher PHP SDK:

composer require pusher/pusher-php-server Setting Up Pusher

Setting up Pusher

To get started with Pusher Channels, sign up for a free Pusher account. Then go to the dashboard and create a new Channels app.

Take note of your app credentials as we’ll be using them shortly. For the purpose of this tutorial, we'll be triggering some client events in our online collaborative note app.

By default, when you create a Channels app, client events are not enabled. We have to enable this for our app. To enable client events in your Pusher app, select the app then click on the App Settings tab, then check the box next to Enable client events.

collaborative-note-app-laravel-enable-clients-events

Now, let’s fill in our app credentials. Update the .env file to contain our Pusher app credentials:

1// .env
2
3PUSHER_APP_ID=xxxxxx
4PUSHER_APP_KEY=xxxxxxxxxxxxxxxxxxxx
5PUSHER_APP_SECRET=xxxxxxxxxxxxxxxxxxxx

Remember to replace the xs with your Pusher Channels app credentials. You can find your app credentials under the Keys section on the overview tab in the Pusher Dashboard.

Also, remember to fill in the cluster of your Pusher Channels app and other additional options.

Installing frontend dependencies

For this tutorial, we’ll be using Bootstrap, Vue and Axios, which have been setup for us by Laravel, though we still need to install each of the dependencies. To compile our CSS and JavaScript, we need to install Laravel Mix, which is a wrapper around Webpack. We can install these dependencies through NPM:

npm install

We also need to install Laravel Echo, which is a JavaScript library that makes it painless to subscribe to channels and listen for events broadcast by Laravel and of course the Pusher JavaScript library:

npm install --save laravel-echo pusher-js

Once installed, we need to tell Laravel Echo to use Pusher. At the bottom of the resources/assets/js/bootstrap.js file, uncomment the Laravel Echo section and update the details with:

1// resources/assets/js/bootstrap.js
2
3import Echo from "laravel-echo"
4
5window.Echo = new Echo({
6    broadcaster: 'pusher',
7    key: xxxxxxxxxxxxxxxxxxxx,
8});

Remember to replace the xs with your Pusher app key.

Authenticating users

As mentioned earlier, our collaborative note app will be only accessible to authenticated users. So, we need an authentication system:

php artisan make:auth

This will create the necessary routes, views and controllers needed for an authentication system.

Before we go on to create users, we need to run the users migration that comes with a fresh installation of Laravel. But to do this, we first need to set up our database. Open the .env file and enter your database details:

1// .env
2
3DB_CONNECTION=mysql
4DB_HOST=127.0.0.1
5DB_PORT=3306
6DB_DATABASE=laravel-notes
7DB_USERNAME=root
8DB_PASSWORD=

Update with your own database details. Now, we can run our migration:

php artisan migrate

NOTE: There’s a bug in Laravel 5.4 if you’re running a version of MySQL older than 5.7.7 or MariaDB older than 10.2.2. This can be fixed by replacing the boot() of app/Providers/AppServiceProvider.php with:

1// app/Providers/AppServiceProvider.php
2
3// remember to use
4Illuminate\Support\Facades\Schema;
5
6/**
7 * Bootstrap any application services.
8 *
9 * @return void
10 */
11public function boot()
12{
13  Schema::defaultStringLength(191);
14}

Note model and migration

Create a Note model along with the migration file by running the command:

php artisan make:model Note -m

Open the Note model and add the code below to it:

1/**
2 * Fields that can not be mass assigned
3 * 
4 * @var array
5 */
6protected $guarded = ['id'];
7
8/**
9 * Get the route key for the model.
10 *
11 * @return string
12 */
13public function getRouteKeyName()
14{
15  return 'slug';
16}

Instead of manually specifying each field that can be mass assigned in the $fillable array, we simply use $guarded and add the id column as the field that can not be mass assigned, meaning every other field can be mass assigned. Laravel route model bind will by default use the id column on the model, but in this tutorial, we want to use the slug column instead, hence the getRouteKeyName method which will simply return the column we want to use for route model binding.

Within the databases/migrations directory, open the notes table migration that was created when we ran the command above and update the up method with:

1Schema::create('notes', function (Blueprint $table) {
2  $table->increments('id');
3  $table->unsignedInteger('user_id');
4  $table->string('title');
5  $table->string('slug')->unique();
6  $table->text('body');
7  $table->timestamps();
8});

Run the migration:

php artisan migrate

Defining app routes

Open routes/web.php and replace the routes with the code below:

1Auth::routes();
2
3Route::get('/', 'NotesController@index');
4Route::get('create', 'NotesController@create');
5Route::post('create', 'NotesController@store');
6Route::get('edit/{note}', 'NotesController@edit');
7Route::patch('edit/{note}', 'NotesController@update');

The routes are straightforward: routes that will handle authentication, a homepage route to list all notes created a user, routes for creating a new note and lastly routes to update a specified note.

NOTE: Since we have removed the /home route, you might want to update the redirectTo property of both app/Http/Controllers/Auth/LoginController.php and app/Http/Controllers/Auth/RegisterController.php to:

protected $redirectTo = '/';

NotesController

Let’s create the controller which will handle the logic of our chat app. Create a NotesController with the command below:

php artisan make:controller NotesController

Open the new create app/Http/Controllers/NotesController.php file and add the following code to it:

1// app/Http/Controllers/NotesController.php
2
3use App\Note;
4
5public function __construct()
6{
7  $this->middleware('auth');
8}
9
10/**
11 * Display a listing of all notes.
12 *
13 * @return \Illuminate\Http\Response
14 */
15public function index()
16{
17  $notes = Note::where('user_id', auth()->user()->id)
18                  ->orderBy('updated_at', 'DESC')
19                  ->get();
20
21  return view('notes.index', compact('notes'));
22}
23
24/**
25 * Show the form for creating a new note.
26 *
27 * @return \Illuminate\Http\Response
28 */
29public function create()
30{
31  return view('notes.create');
32}
33
34/**
35 * Store a newly created note in database.
36 *
37 * @param  \Illuminate\Http\Request  $request
38 * @return \Illuminate\Http\Response
39 */
40public function store(Request $request)
41{
42  $this->validate($request, [
43    'title' => 'required',
44    'body'  => 'required'
45  ]);
46
47  $note = Note::create([
48    'user_id' => $request->user()->id,
49    'title'   => $request->title,
50    'slug'    => str_slug($request->title) . str_random(10),
51    'body'    => $request->body
52  ]);
53
54  return redirect('/');
55}
56
57/**
58 * Show the form for editing the specified note.
59 *
60 * @param  \App\Note  $note
61 * @return \Illuminate\Http\Response
62 */
63public function edit(Note $note)
64{
65  return view('notes.edit', compact('note'));
66}
67
68/**
69 * Update the specified note.
70 *
71 * @param  \Illuminate\Http\Request  $request
72 * @param  \App\Note  $note
73 * @return \Illuminate\Http\Response
74 */
75public function update(Request $request, Note $note)
76{
77  $note->title = $request->title;
78  $note->body = $request->body;
79
80  $note->save();
81
82  return 'Saved!';
83}

Using the auth middleware in NotesController‘s __contruct() indicates that all the methods with the controller will only be accessible to authenticated users. The index method will fetch the notes created by the currently authenticated user and render a view with notes. The create method will display a form to create new note. The store method will do the actual persisting of the note to the database. Notice we're appending a random string to the slug so as to make it unique for each note. The edit method shows the form for editing a specified note. Lastly, the update method handles the actual update and persist to database.

Creating Our Note App Views

When we ran make:auth, Laravel created a master layout called app.blade.php which we are going to leverage with some slight additions. So open resources/view/layouts/app.blade.php and update the left side of the navbar with:

1<!-- resources/view/layouts/app.blade.php -->
2
3<!-- Left Side Of Navbar -->
4<ul class="nav navbar-nav">
5  <li><a href="{{ url('create') }}">Create Note</a></li>
6</ul>

All we did is add a link to create new note on the navbar.

Create new note view

Now, let's create the view for creating a new note. Create a new directory named notes within the views directory. Within the newly created notes directory, create a new file named create.blade.php and paste the code below to it:

1<!-- resources/views/notes/create.blade.php -->
2@extends('layouts.app')
3
4@section('content')
5    <div class="container">
6        <div class="row">
7            <div class="col-md-8 col-md-offset-2">
8                <div class="panel panel-default">
9                    <div class="panel-heading">Create new note</div>
10                    <div class="panel-body">
11                        <form action="{{ url('create') }}" method="POST" class="form" role="form">
12                            {{ csrf_field() }}
13
14                            <div class="form-group{{ $errors->has('title') ? ' has-error' : '' }}">
15                                <input type="text" class="form-control" name="title" value="{{ old('title') }}" placeholder="Give your note a title" required autofocus>
16
17                                @if ($errors->has('title'))
18                                    <span class="help-block">
19                                        <strong>{{ $errors->first('title') }}</strong>
20                                    </span>
21                                @endif
22                            </div>
23
24                            <div class="form-group{{ $errors->has('body') ? ' has-error' : '' }}">
25                                <textarea class="form-control" name="body" rows="15" placeholder="...and here goes your note body" required>{{ old('body') }}</textarea>
26
27                                @if ($errors->has('body'))
28                                    <span class="help-block">
29                                        <strong>{{ $errors->first('body') }}</strong>
30                                    </span>
31                                @endif
32                            </div>
33
34                            <button class="btn btn-primary pull-right">Save</button>
35                        </form>
36                    </div>
37                </div>
38            </div>
39        </div>
40    </div>
41@endsection

This creates a form with two input fields (for title and body of the note respectively) and a save button.

List all notes view

Let's give our users a way to see all the notes they have created. Within the notes directory, create a new file named index.blade.php and paste the code below into it:

1<!-- resources/views/notes/index.blade.php -->
2
3@extends('layouts.app')
4
5@section('content')
6    <div class="container">
7        <div class="row">
8            <div class="col-md-8 col-md-offset-2">
9                <div class="panel panel-default">
10                    <div class="panel-heading">My notes</div>
11                    <div class="panel-body">
12                        @if($notes->isEmpty())
13                            <p>
14                                You have not created any notes! <a href="{{ url('create') }}">Create one</a> now.
15                            </p>
16                        @else
17                        <ul class="list-group">
18                            @foreach($notes as $note)
19                                <li class="list-group-item">
20                                    <a href="{{ url('edit', [$note->slug]) }}">
21                                        {{ $note->title }}
22                                    </a>
23                                    <span class="pull-right">{{ $note->updated_at->diffForHumans() }}</span>
24                                </li>
25                            @endforeach
26                        </ul>
27                        @endif
28                    </div>
29                </div>
30            </div>
31        </div>
32    </div>
33@endsection

The simply displays a message if the user has not created any notes and a link to create a new note. Otherwise it will display all the notes created by the user in a list.

Edit note view

Let's create the edit view which will allow users to edit a note. Within the notes directory, create a new file named edit.blade.php and paste the code below into it:

1<!-- resources/views/notes/edit.blade.php -->
2
3@extends('layouts.app')
4
5@section('content')
6    <div class="container">
7        <div class="row">
8            <div class="col-md-8 col-md-offset-2">
9                <edit-note :note="{{ $note }}"></edit-note>
10            </div>
11        </div>
12    </div>
13@endsection

You will notice we're using a custom tag with the edit view, this is our view component which we'll create shortly.

Now let's create a Vue component. Create a new file named EditNote.vue within resources/assets/js/components directory and paste the code below to it:

1// resources/assets/js/components/EditNote.vue
2
3<template>
4    <div class="panel panel-default">
5        <div class="panel-heading">Edit note</div>
6        <div class="panel-body">
7            <div class="form-group">
8                <input type="text" class="form-control" v-model="title" @keydown="editingNote">
9            </div>
10
11            <div class="form-group">
12                <textarea class="form-control" rows="15" v-model="body" @keydown="editingNote"></textarea>
13            </div>
14
15            <button class="btn btn-primary pull-right" @click="updateNote">Save</button>
16
17            <p>
18                Users editing this note:  <span class="badge">{{ usersEditing.length }}</span>
19                <span class="label label-success" v-text="status"></span>
20            </p>
21        </div>
22    </div>
23</template>
24
25<script>
26    export default {
27        props: [
28            'note',
29        ],
30
31        data() {
32            return {
33                title: this.note.title,
34                body: this.note.body,
35                usersEditing: [],
36                status: ''
37            }
38        },
39
40        mounted() {
41            Echo.join(`note.${this.note.slug}`)
42                .here(users => {
43                    this.usersEditing = users;
44                })
45                .joining(user => {
46                    this.usersEditing.push(user);
47                })
48                .leaving(user => {
49                    this.usersEditing = this.usersEditing.filter(u => u != user);
50                })
51                .listenForWhisper('editing', (e) => {
52                    this.title = e.title;
53                    this.body = e.body;
54                })
55                .listenForWhisper('saved', (e) => {
56                    this.status = e.status;
57
58                    // clear is status after 1s
59                    setTimeout(() => {
60                        this.status = '';
61                    }, 1000);
62                });
63        },
64
65        methods: {
66            editingNote() {
67                let channel = Echo.join(`note.${this.note.slug}`);
68
69                // show changes after 1s
70                setTimeout(() => {
71                    channel.whisper('editing', {
72                        title: this.title,
73                        body: this.body
74                    });
75                }, 1000);
76            },
77
78            updateNote() {
79                let note = {
80                    title: this.title, 
81                    body:  this.body
82                };
83
84                // persist to database
85                axios.patch(`/edit/${this.note.slug}`, note)
86                    .then(response => {
87                        // show saved status
88                        this.status = response.data;
89
90                        // clear is status after 1s
91                        setTimeout(() => {
92                            this.status = '';
93                        }, 1000);
94
95                        // show saved status to others
96                        Echo.join(`note.${this.note.slug}`)
97                            .whisper('saved', {
98                                status: response.data
99                            });
100                    });
101            }
102        }
103    }
104</script>

Let's explain each piece of the code. Just like we have in the 'create new note' form, the template section has two input fields: title and body. Each field is bound to data (title and body respectively). Once a user starts typing (that is, a keydown event) in any of the input fields, the editingNote method will be triggered. Also, when the save button is clicked, the updateNote method will be triggered. (We'll take a close look at these methods soon) Lastly on the template section, we display the number of users who are currently editing the specified note and also display a status message once the save button is clicked.

Moving to the script section of the component, first we define a property for the component called note. This note property will be the note that is currently being edited. Recall from the edit view where we used the EditNote component, you will notice we passed the whole note object as the component's note property. Next we define some data, the title and the body data are bound to respective input fields, the usersEditing will be an array of users editing the note and status will serve as an indicator for when a note's edits have been persisted to the database. The mount method will be triggered immediately the component is mounted, so it's a nice place to subscribe and listen to a channel. In our case, because we to be able to keep track of users editing a note, we'll make use of Pusher's presence channel.

Using Laravel Echo, we can subscribe to a presence channel using Echo.join('channel-name'). As you can see our channel name is note.note-slug. Once we subscribe to a presence channel, we can get all the users that are subscribed to the channel with the here method where we simply assign the subscribed users to the usersEditing array. When a user joins the channel, we simply add that user to the usersEditing array. Similarly, when a user leaves the channel, we remove that user from the usersEditing array. To display edits in realtime to other users, we listen for client events that are triggered as a user types using listenForWhisper and update the form data accordingly. In the same vein, we listen for when edits are saved and display the "Saved!" status to other users, then after a second we clear the status message.

Next, we define the methods we talked about earlier. The editingNote method simply triggers a client event to all users currently subscribed to the channel after a specified time (1 second). The updateNote method on the other hand sends a PATCH request with the edits made to persist the edits to the database. Once the request is successful, we display the message saved status to the user that made the save and clear the status message after 1 second. Lastly, we trigger a client event so other users can also see the message saved status.

Since we created a presence channel, only authenticated users will be able to subscribe and listen on the note channel. So, we need a way to authorize that the currently authenticated user can actually subscribe and listen on the channel. This can be done in the routes/channels.php file:

1// routes/channels.php
2
3Broadcast::channel('note.{slug}', function ($user, $slug) {
4    return [
5        'id'   => $user->id,
6        'name' => $user->name
7    ];
8});

We pass to the channel(), the name of our channel and a callback function that will return the details of the user if the current user is authenticated.

Now let's register our new created component with our Vue instance, open resources/assets/js/app.js and add the line below just before Vue instantiation:

1// resources/assets/js/app.js
2
3Vue.component('edit-note', require('./components/EditNote.vue'));

Before testing out our online collaborative note app, we need to compile the JavaScript files using Laravel Mix using:

npm run dev

Now we can start our note app by running:

php artisan serve

Conclusion

We have seen how to build a simple online collaborative note app using Laravel and Pusher. Sure there are other ways of accomplishing what we did in this tutorial, but we have seen how to build a collaborative app with Pusher's realtime features. Also you will notice our note app doesn’t account for cases like concurrent editing of notes; to achieve that you'd want to look into Operational Transformation.

Docs

Tutorials

Support

Glossary