Lumen Programming Guide: Writing PHP Microservices, REST and Web Service APIs

258 Pages·2016·7.02 MB·English

by  Paul Redmond (auth.)

Lumen
Programming
Guide
Writing PHP Microservices, REST and
Web Service APIs
—
Paul Redmond
L umen
Programming Guide
W riting PHP Microservices, REST
and Web Service APIs
P aul Redmond
Lumen Programming Guide: Writing PHP Microservices, REST and Web Service APIs
Paul Redmond
Phoenix, Arizona
USA
ISBN-13 (pbk): 978-1-4842-2186-0 ISBN-13 (electronic): 978-1-4842-2187-7
DOI 10.1007/978-1-4842-2187-7
Library of Congress Control Number: 2016953766
Copyright © 2016 by Paul Redmond
This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the
material is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation,
broadcasting, reproduction on microfilms or in any other physical way, and transmission or information
storage and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now
known or hereafter developed.
Trademarked names, logos, and images may appear in this book. Rather than use a trademark symbol with
every occurrence of a trademarked name, logo, or image we use the names, logos, and images only in an
editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark.
The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are
not identified as such, is not to be taken as an expression of opinion as to whether or not they are subject to
proprietary rights.
While the advice and information in this book are believed to be true and accurate at the date of publication,
neither the authors nor the editors nor the publisher can accept any legal responsibility for any errors or
omissions that may be made. The publisher makes no warranty, express or implied, with respect to the
material contained herein.
Managing Director: Welmoed Spahr
Lead Editor: Steve Anglin
Technical Reviewer: Jacob Jensen
Editorial Board: Steve Anglin, Pramila Balan, Laura Berendson, Aaron Black, Louise Corrigan,
Jonathan Gennick, Robert Hutchinson, Celestin Suresh John, Nikhil Karkal, James Markham,
Susan McDermott, Matthew Moodie, Natalie Pao, Gwenan Spearing
Coordinating Editor: Mark Powers
Copy Editor: Mary Behr
Compositor: SPi Global
Indexer: SPi Global
Artist: SPi Global
Cover image designed by Freepik
Distributed to the book trade worldwide by Springer Science+Business Media New York, 233 Spring Street,
6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax [phone], e-mail o
T o Bernadette
Contents at a Glance
About the Author ..................................................................................................... xi
About the Technical Reviewer ............................................................................... xiii
Acknowledgments ...................................................................................................xv
Introduction ...........................................................................................................xvii
■ Chapter 1: Installing Lumen .................................................................................. 1
■ Chapter 2: Hello Lumen ......................................................................................... 7
■ Chapter 3: Creating the Book Application ........................................................... 17
■ Chapter 4: Starting the Books API ....................................................................... 23
■ Chapter 5: Creating, Reading, Updating, and Deleting Books .............................. 33
■ Chapter 6: Responding to Errors ......................................................................... 65
■ Chapter 7: Leveling Up Responses ...................................................................... 89
■ Chapter 8: Validation ......................................................................................... 125
■ Chapter 9: Authors ............................................................................................ 137
■ Chapter 10: The /authors API Resource ............................................................ 165
■ Chapter 11: Book Bundles ................................................................................. 201
■ Chapter 12: Ratings ........................................................................................... 219
■ Appendix: Where to Go From Here ..................................................................... 243
Index ..................................................................................................................... 245
v
Contents
About the Author ..................................................................................................... xi
About the Technical Reviewer ............................................................................... xiii
Acknowledgments ...................................................................................................xv
Introduction ...........................................................................................................xvii
■ Chapter 1: Installing Lumen .................................................................................. 1
Homestead ....................................................................................................................... 1
Mac OSX ........................................................................................................................... 2
Linux ................................................................................................................................. 3
Red Hat/CentOS ...................................................................................................................................... 4
Debian/Ubuntu ........................................................................................................................................ 5
Windows ........................................................................................................................... 6
Conclusion ........................................................................................................................ 6
■ Chapter 2: Hello Lumen ......................................................................................... 7
Setting Up a New Project ................................................................................................. 7
Routes .............................................................................................................................. 9
The Hello World Route .......................................................................................................................... 10
Route Parameters ................................................................................................................................. 10
Middleware and Responses ........................................................................................... 11
Global Middleware ................................................................................................................................ 11
Route Middleware................................................................................................................................. 13
vii
■ CONTENTS
The Request and Response Objects ............................................................................... 14
The Request .......................................................................................................................................... 15
The Response ....................................................................................................................................... 15
Onward ........................................................................................................................... 16
■ Chapter 3: Creating the Book Application ........................................................... 17
Building Something Amazing ......................................................................................... 17
Environment Setup ......................................................................................................... 19
Checking Unit Tests ........................................................................................................ 21
Setup Complete .............................................................................................................. 22
■ Chapter 4: Starting the Books API ....................................................................... 23
Creating the First Endpoint ............................................................................................. 23
Setting Up Models and Seed Data .................................................................................. 26
Eloquent Books .............................................................................................................. 30
Success .......................................................................................................................... 32
■ Chapter 5: Creating, Reading, Updating, and Deleting Books .............................. 33
Requesting an Individual Book ....................................................................................... 33
Creating a New Book ...................................................................................................... 41
Updating an Existing Book ............................................................................................. 49
Deleting Books ............................................................................................................... 53
Conclusion ...................................................................................................................... 63
■ Chapter 6: Responding to Errors ......................................................................... 65
Test Database ................................................................................................................. 65
Model Factories .................................................................................................................................... 66
Factories in Tests .................................................................................................................................. 66
Better Error Responses .................................................................................................. 69
Framework Exception Handling ............................................................................................................ 70
JSON Exceptions .................................................................................................................................. 72
Testing the Exception Handler ........................................................................................ 74
Conclusion ...................................................................................................................... 88
viii
■ CONTENTS
■ Chapter 7: Leveling Up Responses ...................................................................... 89
Introducing Fractal ......................................................................................................... 89
First Version of API Response Formatting ...................................................................... 90
The Fractal Response Class ........................................................................................... 97
The Book Transformer .......................................................................................................................... 97
The Fractal Response Class................................................................................................................ 101
Fractal Response Service ............................................................................................. 111
Integrating the Fractal Response Service .................................................................... 114
Conclusion .................................................................................................................... 124
■ Chapter 8: Validation ......................................................................................... 125
First Attempt at Validation ............................................................................................ 125
More Validation Constraints ......................................................................................... 129
Custom Validation Messages ....................................................................................... 132
Other Approaches ......................................................................................................... 134
Conclusion .................................................................................................................... 135
■ Chapter 9: Authors ............................................................................................ 137
The Authors Database Schema .................................................................................... 137
Fixing Broken Tests ...................................................................................................... 145
Conclusion .................................................................................................................... 163
■ Chapter 10: The /authors API Resource ............................................................ 165
The GET /authors Endpoint ........................................................................................... 166
The AuthorsTransformer ..................................................................................................................... 166
The Author Controller .......................................................................................................................... 168
The GET /authors/{id} Endpoint .................................................................................... 170
A Basic Response ............................................................................................................................... 170
Including Other Models in the Response ............................................................................................ 171
The POST /authors Endpoint......................................................................................... 181
The PUT /authors/{id} Endpoint .................................................................................... 188
ix
■ CONTENTS
The DELETE /authors/{id} Endpoint .............................................................................. 197
Conclusion .................................................................................................................... 199
■ Chapter 11: Book Bundles ................................................................................. 201
Defi ning the Relationship Between Books and Bundles .............................................. 201
The GET /bundles/{id} Endpoint .................................................................................... 206
Adding a Book to a Bundle ........................................................................................... 214
Remove a Book from a Bundle ..................................................................................... 215
Conclusion .................................................................................................................... 217
■ Chapter 12: Ratings ........................................................................................... 219
Database Design .......................................................................................................... 219
Rating an Author ........................................................................................................... 223
Adding an Author Rating ..................................................................................................................... 223
Deleting an Author Rating ................................................................................................................... 233
Ratings in the Author API .............................................................................................. 236
Eager Loading Ratings ................................................................................................. 240
Conclusion .................................................................................................................... 242
■ Appendix: Where to Go From Here ..................................................................... 243
Laravel .......................................................................................................................... 243
Laracasts ...................................................................................................................... 243
Mockery ....................................................................................................................... 244
Guzzle ........................................................................................................................... 244
Index ..................................................................................................................... 245
x
A bout the Author
P aul R edmond h as worked as a web developer, entrepreneur, and mentor
in software development for over a decade. He has built web applications
within startups, agencies, and enterprise customers with open-source
technologies. Paul is passionate about writing highly available applications
with PHP, JavaScript, and RESTful APIs.
P aul lives in Scottsdale, Arizona with his wife, Bernadette, three boys,
and one cat. He is usually wrangling code, kittens, and children, but finds
time to enjoy reading fantasy/fiction, writing, and watching sports.

xi