So far, I've been quite impressed with Drupal. It's a lot better than I had been led to believe, and the workflow is far superior to working with WordPress, even with Bedrock.
Drupal has been around since before I started my development career, but I hadn't used it before, and had always assumed it was rather dated. To my surprise, Drupal actually satisfies most of what I want in a PHP CMS nowadays:
drupal/recommended-project and use it as a basis for your projectAlso, it's noticeable that it's flexible enough that a lot of functionality which in other CMS solutions would require a plugin (cough... WordPress) or bespoke development can be done with just the core CMS. This eliminates the "wood for the trees" issue I've had with WordPress whereby you can find many plugins that do sort of what you want, but all of them seem to cater to a specific use case that's not quite what you want. For instance, if I needed to create event listing functioality, all I would need to do is to create a new content type for the events with the required fields (possibly with another content type for the locations and a relation between them).
I'd always heard that Drupal was particularly hard to use, but after having used it for a bit, I really don't agree with that. I came to it after having used multiple other CMS solutions and if you've already been exposed to the underlying concepts like taxonomies and different content types, it's really not hard to understand. It has a powerful permissions system that allows you to grant and remove permissions in a very granular way, and the only way I could see clients struggling to understand it would be if they were given permissions that they didn't need - a good developer shouldn't be doing this.
I'm sure that prior versions of Drupal would have been much worse on these points, but I so far haven't used a version below 10 so I can't really comment on it. I'm impressed that unlike with Wordpress, they haven't been afraid to make breaking changes for the sake of the long-term health of the project and haven't left in in a state where it's a tired backwater of bad practices that's able to keep going solely due to the popularity of the platform.
I maintain a large legacy Zend 1 application at work, and a rewrite of that has been on the cards for a while. Drupal is the first off the shelf CMS where I haven't been able to dismiss using it as the basis of a rewrite out of hand. I honestly couldn't conclusively say at the moment how viable it would be to rebuild it from scratch in Drupal, since it would depend on a lot of bespoke module development that I wouldn't yet feel confident about quoting for, but the mere fact I haven't been able to dismiss it is a testament to its flexibility and power. Working with Drupal so far hasn't felt like I'm stuck in a ghetto of bad practices and dated code like it does with WordPress.
I don't want this to sound like a sponsored post, and so far my experience with it is quite limited, but so far I've been pleasantly surprised by how good Drupal is these days. It's a far more modern PHP CMS than WordPress, and the developer experience is a lot better. While I haven't really got too far into it and have yet to delve into bespoke theme and module development, I'm looking forward to doing so in the future.
]]>It's been inevitable for a while that this had to happen, and here's why.
The package doesn't actually do very much itself. Laravel's Filesystem storage abstraction is built on top of the Flysystem package, and uses that to provide the underlying functionality to integrate with multiple storage backends. Writing a custom driver for this is therefore pretty easy as long as there's an existing Flysystem driver for the storage method in question.
In March 2023 Microsoft announced that they were retiring the PHP SDK for working with Azure Storage, in favour of working directly with the REST API. Off the back of this, the creator of Flysystem announced he could no longer maintain the Azure driver as a result of this, and that it too would be retired at the same time. As my package was directly dependent on the Flysystem package, which was itself also dependent on the PHP SDK, if it was going to have any future, then barring replacement packages for both of those, it was going to have to be completely rebuilt to include the functionality of both third party packages.
If I had a genuine need for the package, it might have been worth doing so, however that wasn't the case. I've actually never used this package myself except for testing. I originally worked with Azure Blob Storage in a Laravel application I built in 2015 at a previous employer, which was the first time I'd used Laravel, and used Graham Campbell's Flysystem package. It was only later that I realised I could have had a better experience by rolling a custom driver, and wound up producing the package. In the intervening period a few people contributed features and bug fixes, and I tightened up the code base a bit with type checking, more comprehensive tests, and better documentation, but the core of it didn't change much. It remained something of an annoyance to some extent - something I'd created for a specific project that I never even used, but wound up maintaining anyway.
Ironically, I did actually have a client at work wanting to use Azure Blob Storage for a use case only the other day. I'd built out a command line script that generated some text files and dropped them into a storage medium using Flysystem, and the client asked if they could use Azure storage for it. The Flysystem driver would have been useful for that, but as it's being retired I don't want to use it, and will instead need to move it away from Flysystem and work directly with the REST API to store the files. As it's not a Laravel project, I wouldn't find this project useful anyway, but the fact that I've only used Azure storage twice in my career, and those nearly two decades apart, emphasises that it's really not worth my time to continue working on this package if I need to do a load more development on it to keep it viable.
As at right now, there does seem to be an effort to create an open source fork of the underlying Microsoft PHP SDK. This only covers the Microsoft SDK, not the Flysystem Azure driver, or this package, so it's not a drop in replacement for this, however there is talk on the issues of that repository around creating a Flysystem driver and possibly forking this package to work with it.
You could potentially fork this package and the Flysystem Azure driver, and adjust them both to use that package, but that would be a fair amount of work, and is probably only worth doing if you really have to continue using Azure Blob Storage and can't switch to an alternative like Amazon S3 or Digital Ocean Spaces.
Saying goodbye to this package will be a relief. It's been a bit of a time sink given the fact I've never used it, and given I have only had limited dealings with the Azure ecosystem since it was always a pain to maintain and test. It also provided some useful lessons on how to accept issues on GitHub - many of the feature requests and bug fixes were for things the package couldn't do because it was just a layer on top of Flysystem, so I wound up producing some quite complex issue templates to weed out things I couldn't do a thing about or that needed to be done in one of the dependencies.
]]>One issue in particular that has been bugging me for a long time is misinformation about application performance, particularly when relating to Laravel. If you visit many PHP or web development-related communities, such as the PHP subreddit, it's quite common for inexperienced developers to post questions along the lines of "What is the fastest framework?". A lot of barely-more experienced commenters will then leap in with ill-informed comments about which frameworks are supposedly slower or faster, based on benchmarks. In actual fact, the idea of a framework being faster or slower really doesn't make sense - a framework isn't an application, the way something like WordPress is, and to compare the same "Hello world" application implemented in different frameworks gives a really poor idea of what the real reasons for poor application performance are. The actual causes of a slow application are nearly always something that isn't framework specific, and rewriting a working application into a supposedly "faster" framework won't generally resolve the issue.
And that, in a nutshell, is why I've created High Performance Laravel. It's intended to be a repository of articles that will explain the following:
A lot of this isn't necessarily specific either to Laravel or PHP, but it's written from the perspective of a Laravel developer. As such, if you work with a different framework or language, you still might find plenty of useful content there.
]]>I've come to appreciate that explicitly declaring every class you can as either abstract or final is a powerful method for enforcing certain aspects of good software design, for the following reasons:
If you declare a class as final, you are stating to any other developers that it's designed to do one thing, and one thing only, and so it's not intended to be extended to do something else. This is consistent with the Single Responsibility principle in SOLID.
Similarly, if you declare a class as abstract, you are stating to any other developers working with the code that this class has been designed specifically to be extended, and so they should feel free to do so as appropriate.
It's relatively easy to design a class to do one thing and one thing only. It's a lot harder to design a class to do multiple things, or to do things in a generic fashion, and it's outright dangerous to just assume that your use case for something isn't different enough that you're going to have problems if you extend a class that's not designed to be extended.
It also means you're dependent on the private API of the code you're extending remaining compatible with the rest of the code. If you extend a third-party class, and make use of private methods declared on that class, then potentially any changes made to that class can break your class, not just documented changes to the public API.
In addition, if you develop or maintain a library, framework or other application that can be extended by other developers such as a content management system, declaring all your classes as abstract or final can potentially save you a lot of grief. If you receive a bug report on said project which touches on a class that is neither abstract nor final, it's entirely possible that said class has been inappropriately extended, and that the issue is actually caused by something in the reporter's class which extends yours.
We've all seen it, a long chain of classes where each one extends a preceding one slightly, with the ones lowest in the chain having been amended just to fix some minor inconvenience. Often the change is itself something comparatively trivial, such as a getter or setter, but often it's something that would be better solved through other means. Which leads us to...
Consider the use case of an existing class within a framework which fetches a user based on an ID, and can be swapped with an alternative implementation of the same class. This class means that every time the page loads while a user is logged in, it carries out the same query to get the user. This query could potentially be cached to improve application performance.
You could extend that class and add caching, but it's not a very good way to do it:
So instead, you could use composition, by creating a decorator class, which implements the same interface as the original class, but wraps the original class in a caching layer. This resolves both issues:
This isn't a purely theoretical example - I've used exactly this approach myself in Laravel. And it's a far more elegant, flexible and reusable approach than extending the class.
For many classes in a typical project, particularly those built with an off-the-shelf MVC framework, you'll never need to extend them. Migrations are a good example of this - each migration does one thing and one thing only, and if you extend a migration you're doing something seriously dodgy. And there's very little need to ever extend controllers - if you're building a REST API, it might be useful to place common functionality in one resource controller for reuse, but it just doesn't make sense to extend one concrete class with another. Instead you're better off creating an abstract ResourceController class, and having your concrete resource classes extend that.
No, and this is a very bad misconception it took me years to unlearn.
The first web application I built solo in PHP, back in 2012, was using CodeIgniter 2, and at that point in my career I was still writing what was effectively procedural code, but stuffing it inside objects. That wasn't OOP, and it wasn't for around another five years before I realised that OOP wasn't about just putting code in objects, but about the interactions between objects. Nowadays, I rarely use primitive types such as arrays and scalar variables, because objects that can be more specifically typed are more type-safe (making tools like Psalm happier), and you can add functionality to them to make interactions easier.
The more granular you can make a class, the more likely it is that it can be easily reused (again, this is part of the single responsibility principle). Understanding this was a pivotal moment in my career. If each class is a relatively small thing that does one thing only, and depends on an interface, code reuse really doesn't require inheritance all that often. It's actually quite rare these days that I have any need whatsoever to extend a class, because most of my classes can be reused as-is, without the need for any changes, or if they do need extending, I can do so via composition.
No, you can't, unless you're going to jump through hoops to do so. However, a sufficiently well-designed class shouldn't need you to do that anyway. For an awful lot of use cases, mocking isn't the best option anyway during testing:
This is a code smell, suggesting that said class is probably too large, and does too much. You should consider extracting that functionality into a new class, which is then a dependency of that class.
For instance, say you have a library that sends emails to users, and that has drivers for, say, SMTP, and the Mailgun API. Suppose you want to create a new driver for Mailchimp transactional emails which also works over HTTP, so you want to reuse some of the functionality from the Mailgun driver. Extending the Mailgun driver to reuse the HTTP request functionality that makes the requests might allow you to achieve that, but it causes several additional problems:
Under these circumstances, the best solution would likely be to create a Transport interface, extract the HTTP functionality into a new HttpTransport class that implements the Transport interface, and then use the class in both the Mailgun and Mailchimp drivers. This would also allow the transport method to be mocked, so it could be tested more easily without sending actual HTTP requests. Another option might be to extract the HTTP functionality to an HttpDriver abstract class, which is extended by both the Mailgun and Mailchimp API drivers.
No, it's more complex than that.
If I'm not your line manager or a member of the same development team, I'm not responsible for your training and personal development as a coder, and likely can have little influence on that. But even if our only interaction is in regards to, say, a library I wrote and put on Github that you're using, I have a vested interest in making sure you use it in a way I'd consider safe. If you go and extend it and report a bug that turns out to be in a class that extends mine, that's going to be a waste of my time to deal with. And I can fill my documentation with notes about "This class isn't meant to be extended. Don't extend it", but I've still got no guarantees. But if I add one single final keyword I have a cast-iron guarantee that it's impossible to extend, and I don't need to think about it any more.
Preventing people from taking the quick and easy way of extending a class that's not intended to be extended also stops quick-and-dirty solutions, and enables teachable moments. If someone on my team can't extend a class I wrote, they'll go looking for other ways around it, and will likely discover a more appropriate alternative, such as the decorator pattern. And if someone does the same with an open source library I wrote, either they'll do the same through research, or if they come to me, I merely need to point them at a more appropriate alternative approach.
Not in the slightest. Here are some other posts by experienced PHP developers that cover the same subject:
There are a number of ways you can do so:
Explicitly declaring all classes I can as either abstract or final has greatly improved the quality of my code. It's forced me to up my game in terms of application design, by stopping me from taking all kinds of dodgy shortcuts, and to find better solutions. It's also encouraged me to shrink my classes down to be more granular, enabling code reuse without extension. I highly recommend giving it a try if you aren't already, and seeing what kind of difference it makes to the code you write in the long term.
WITH RECURSIVE common table expression and using closure tables.WITH RECURSIVEA common table expression (CTE) is a temporary result set that is defined within the execution scope of a single SQL statement. In MySQL, you can use the WITH RECURSIVE clause to define a CTE that can be used to retrieve all of the users above or below a given user in the hierarchy.
Say we have a users table that looks like this:
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name VARCHAR(255) NOT NULL,
manager_id INTEGER REFERENCES users(id)
);
To create a CTE that gets the users above a given user, you can use the following query:
WITH RECURSIVE managers AS (
SELECT id, name, manager_id
FROM users
WHERE id = :user_id
UNION ALL
SELECT u.id, u.name, u.manager_id
FROM users u
INNER JOIN managers m ON m.manager_id = u.id
)
SELECT * FROM managers;
This query uses the WITH RECURSIVE clause to define a CTE called managers that first selects the user with the given user_id and then uses the UNION ALL operator to combine that user with all of the users above them in the hierarchy. The INNER JOIN clause is used to link the managers CTE to the users table, so that the managers CTE can keep growing until it includes all of the users above the given user in the hierarchy.
To get the users below a given user, you can use a similar query, but with the manager_id and id fields swapped in the INNER JOIN clause:
WITH RECURSIVE subordinates AS (
SELECT id, name, manager_id
FROM users
WHERE id = :user_id
UNION ALL
SELECT u.id, u.name, u.manager_id
FROM users u
INNER JOIN subordinates s ON s.id = u.manager_id
)
SELECT * FROM subordinates;
This query uses the same technique as the previous example, but it retrieves the users below the given user instead of above.
Another technique for handling recursive relationships in MySQL is to use closure tables. A closure table is a special type of table that is used to represent hierarchical data in a relational database. It consists of two tables: one for the entities in the hierarchy (e.g. users) and one for the relationships between those entities.
To create a closure table for a hierarchy of users, you can use the following DDL statement:
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name VARCHAR(255) NOT NULL
);
CREATE TABLE hierarchy (
ancestor INTEGER NOT NULL REFERENCES users(id),
descendant INTEGER NOT NULL REFERENCES users(id),
PRIMARY KEY (ancestor, descendant),
CHECK (ancestor != descendant)
);
The users table is similar to the one in the previous example, but it only contains the id and name fields. The relationships between the users are defined in the hierarchy table.
To insert data into these tables, you would first need to insert rows into the users table for each user in the hierarchy, and then insert rows into the hierarchy table to define the relationships between those users. Here is an example of how this could be done:
INSERT INTO users (id, name) VALUES
(1, 'Alice'),
(2, 'Bob'),
(3, 'Carol'),
(4, 'Dave'),
(5, 'Eve');
INSERT INTO hierarchy (ancestor, descendant) VALUES
(1, 1),
(1, 2),
(1, 3),
(1, 4),
(1, 5),
(2, 2),
(2, 3),
(2, 4),
(3, 3),
(4, 4);
This inserts five users into the users table and then inserts rows into the hierarchy table to define the relationships between those users. The ancestor and descendant values are both set to the same id for each user, which indicates that each user is a descendant of themselves. The hierarchy table also defines the relationships between the users, with each user being a descendant of the user above them in the hierarchy.
To get all of the users above a given user using a closure table, you can use the following query:
SELECT u.*
FROM users u
INNER JOIN hierarchy h ON h.descendant = :user_id
WHERE u.id = h.ancestor
This query uses an INNER JOIN to link the users table to the hierarchy table, and then filters the results to only include users that are ancestors of the user with the given user_id. This query will return a list of all of the users above the given user in the hierarchy.
To get the users below a given user, you can use a similar query, but with the ancestor and descendant fields swapped in the INNER JOIN clause:
SELECT u.*
FROM users u
INNER JOIN hierarchy h ON h.ancestor = :user_id
WHERE u.id = h.descendant
This query will return a list of all of the users below the given user in the hierarchy.
One downside of the closure table approach is that when the hierarchical structure changes, the hierarchy table needs to be updated to reflect the changes. There are a number of approaches you can take to handle this, including:
hierarchy table automatically when a user is inserted, updated or deletedhierarchy table from scratchThe first approach is generally the most efficient, but has the downside that triggers aren't generally exported from mysqldump, making it difficult to manage when importing the production database locally. The last approach often makes the most sense in cases where users are populated from some kind of regular import, in which case the hierarchy will only ever change as a result of that import.
Which of these approaches you should choose in a given situation is highly dependent on the specific needs of your application, since each has advantages and limitations.
Using a closure table results in a smaller, simpler, and generally more efficient query that is easy to express using an ORM or query builder, but requires that you take steps to update the separate closure table when the hierarchy changes. Using the WITH RECURSIVE CTE doesn't require a separate table, eliminating the need to populate said table, but for some queries it may not be as efficient. In addition, it can be difficult to express with some ORMs and query builders, necessitating either additional third party packages or falling back to raw queries. If you're stuck using an older version of MySQL, such as on a legacy application, and can't upgrade, you might also not be able to use WITH RECURSIVE (though at this point you really shouldn't be using a version that old).
At times I've found it necessary to combine both techniques. One application I maintain has a nightly import process for all the users and derives the permissions to view various pieces of content in part from the hierarchy - the only way to determine the hierarchy is by following the line managers back all the way to the managing director for each individual user, but permissions can be assigned to individual business units within the company and cascade down to child business units, and so to know what permissions a user has, we need to know where they sit in the hierarchy. This query would be too cumbersome to perform on the fly for each user, so we use the WITH RECURSIVE CTE to detetermine a user's place within the hierarchy, and then populate a closure table from it, as a part of the nightly import.
In MySQL, there are a number of techniques that can be used to handle recursive relationships in hierarchical data, but two of the most performant and flexible are the WITH RECURSIVE CTE and using closure tables. Both techniques have their own benefits and drawbacks, and the best choice will depend on the specific requirements of your application.
Naturally I decided to have a tinker with it as I was curious about it, and I've found it very useful for coding. Here are some samples of things I've asked it to do for me.
Given the popularity of React.js and my own experience using it, I figured that was something ChatGPT would probably handle OK and that I would be able to evaluate for myself. I therefore asked ChatGPT to create a React-based alert system for me. As I've implemented something similar myself, I was interested to see how well it would do against my own implementation which is in production:
Please create a hook-based toast-style alert system in React.js using hooks
It responded with:
Sure, here is an example of a toast-style alert system in React.js using hooks:
import React, { useState, useEffect } from 'react';
function useToast() {
const [isShowing, setIsShowing] = useState(false);
const [message, setMessage] = useState('');
function showToast(msg) {
setMessage(msg);
setIsShowing(true);
}
function hideToast() {
setIsShowing(false);
}
useEffect(() => {
let timeoutId;
if (isShowing) {
timeoutId = setTimeout(() => setIsShowing(false), 3000);
}
return () => clearTimeout(timeoutId);
}, [isShowing]);
return {
isShowing,
message,
showToast,
hideToast
};
}
function App() {
const { isShowing, message, showToast, hideToast } = useToast();
return (
<div>
{isShowing && (
<div className="toast">
<p>{message}</p>
<button onClick={hideToast}>Close</button>
</div>
)}
<button onClick={() => showToast('This is a toast message!')}>
Show Toast
</button>
</div>
);
}
In this example, the
useToasthook manages the state for the toast, including whether it is showing, the message to display, and methods for showing and hiding the toast. TheAppcomponent uses theuseToasthook to show and hide the toast when a button is clicked.
The
useToasthook uses theuseStatehook to manage the state for the toast, and theuseEffecthook to automatically hide the toast after a certain amount of time. This is just one example of how to implement a toast-style alert system in React.js using hooks, and you can modify it to suit your specific needs.
Looks OK, but it only supports a single message at once, so I followed it up:
Can we amend this to support showing multiple toasts at once?
Yes, it is possible to modify the example to support showing multiple toasts at once. Instead of using a single state value for the message and whether the toast is showing, you can use an array to store multiple toast messages and show them all at once. Here is an example of how you might do this:
import React, { useState, useEffect } from 'react';
function useToast() {
const [toasts, setToasts] = useState([]);
function showToast(msg) {
setToasts(prevToasts => [...prevToasts, msg]);
}
function hideToast(index) {
setToasts(prevToasts => {
prevToasts.splice(index, 1);
return [...prevToasts];
});
}
useEffect(() => {
let timeoutIds = [];
toasts.forEach((_, index) => {
timeoutIds[index] = setTimeout(() => hideToast(index), 3000);
});
return () => timeoutIds.forEach(timeoutId => clearTimeout(timeoutId));
}, [toasts]);
return {
toasts,
showToast,
hideToast
};
}
function App() {
const { toasts, showToast, hideToast } = useToast();
return (
<div>
{toasts.map((toast, index) => (
<div className="toast" key={index}>
<p>{toast}</p>
<button onClick={() => hideToast(index)}>Close</button>
</div>
))}
<button onClick={() => showToast('This is a toast message!')}>
Show Toast
</button>
</div>
);
}
In this example, the
useToasthook uses an array to store multiple toast messages, and theAppcomponent displays all of the toasts in the array. TheuseEffecthook is used to set a timeout for each toast to automatically hide it after a certain amount of time. You can modify this example further to suit your specific needs, such as setting different timeouts for each toast or adding additional methods for managing the toasts.
Great, although I noticed an unused _ variable in forEach - not sure if perhaps this is based on something that used Lodash, perhaps.
Next, our toasts need to show different styles based on the type of alert, so I asked this:
Can we amend this to allow the toasts to use different styles based on the type of alert?
Yes, it is possible to modify the example to allow the toasts to use different styles based on the type of alert. You can do this by storing the type of each toast along with the message in the state, and then using this type to determine the style for the toast. Here is an example of how you might do this:
import React, { useState, useEffect } from 'react';
function useToast() {
const [toasts, setToasts] = useState([]);
function showToast(msg, type) {
setToasts(prevToasts => [...prevToasts, { msg, type }]);
}
function hideToast(index) {
setToasts(prevToasts => {
prevToasts.splice(index, 1);
return [...prevToasts];
});
}
useEffect(() => {
let timeoutIds = [];
toasts.forEach((_, index) => {
timeoutIds[index] = setTimeout(() => hideToast(index), 3000);
});
return () => timeoutIds.forEach(timeoutId => clearTimeout(timeoutId));
}, [toasts]);
return {
toasts,
showToast,
hideToast
};
}
function App() {
const { toasts, showToast, hideToast } = useToast();
return (
<div>
{toasts.map((toast, index) => (
<div
className={`toast toast-${toast.type}`}
key={index}
>
<p>{toast.msg}</p>
<button onClick={() => hideToast(index)}>Close</button>
</div>
))}
<button onClick={() => showToast('This is a success toast!', 'success')}>
Show Success Toast
</button>
<button onClick={() => showToast('This is an error toast!', 'error')}>
Show Error Toast
</button>
</div>
);
}
In this example, the
useToasthook stores the message and type of each toast in the state, and theAppcomponent uses the type to determine the class name for the toast. This allows you to define different styles for each type of toast, such as atoast-successclass for success toasts and atoast-errorclass for error toasts. You can modify this example further to suit your specific needs, such as defining additional types of toasts or changing the way that the styles are applied.
Great, but a reducer may make more sense than regular state for this use case. Let's ask it to update the code:
Can we amend this code to use a reducer instead of state?
Yes, it is possible to modify the example to use a reducer instead of state. A reducer is a function that takes the current state and an action as arguments, and returns a new state based on the action. This allows you to manage the state for your toast in a more modular and scalable way. Here is an example of how you might do this:
import React, { useReducer, useEffect } from 'react';
const initialState = {
toasts: []
};
function reducer(state, action) {
switch (action.type) {
case 'SHOW_TOAST':
return {
...state,
toasts: [...state.toasts, action.payload]
};
case 'HIDE_TOAST':
const newToasts = [...state.toasts];
newToasts.splice(action.payload, 1);
return {
...state,
toasts: newToasts
};
default:
return state;
}
}
function useToast() {
const [state, dispatch] = useReducer(reducer, initialState);
function showToast(msg, type) {
dispatch({
type: 'SHOW_TOAST',
payload: { msg, type }
});
}
function hideToast(index) {
dispatch({
type: 'HIDE_TOAST',
payload: index
});
}
useEffect(() => {
let timeoutIds = [];
state.toasts.forEach((_, index) => {
timeoutIds[index] = setTimeout(() => hideToast(index), 3000);
});
return () => timeoutIds.forEach(timeoutId => clearTimeout(timeoutId));
}, [state.toasts]);
return {
toasts: state.toasts,
showToast,
hideToast
};
}
function App() {
const { toasts, showToast, hideToast } = useToast();
return (
<div>
{toasts.map((toast, index) => (
<div
className={`toast toast-${toast.type}`}
key={index}
>
<p>{toast.msg}</p>
<button onClick={() => hideToast(index)}>Close</button>
</div>
))}
<button onClick={() => showToast('This is a success toast!', 'success')}>
Show Success Toast
</button>
<button onClick={() => showToast('This is an error toast!', 'error')}>
Show Error Toast
</button>
</div>
);
}
In this example, the
useToasthook uses theuseReducerhook to manage the state for the toast. The reducer function takes the current state and an action as arguments, and returns a new state based on the action. TheAppcomponent dispatches actions to show and hide the toast, and theuseEffecthook is used to set a timeout for each toast to automatically hide it after a certain amount of time
OK, that's done. Now we decide we need this in Typescript:
Please convert this to Typescript
Sure, here is an example of how you might convert the code to TypeScript:
import React, { useReducer, useEffect } from 'react';
interface ToastState {
toasts: {
msg: string;
type: string;
}[];
}
const initialState: ToastState = {
toasts: []
};
function reducer(state: ToastState, action: { type: string; payload: any }) {
switch (action.type) {
case 'SHOW_TOAST':
return {
...state,
toasts: [...state.toasts, action.payload]
};
case 'HIDE_TOAST':
const newToasts = [...state.toasts];
newToasts.splice(action.payload, 1);
return {
...state,
toasts: newToasts
};
default:
return state;
}
}
function useToast() {
const [state, dispatch] = useReducer(reducer, initialState);
function showToast(msg: string, type: string) {
dispatch({
type: 'SHOW_TOAST',
payload: { msg, type }
});
}
function hideToast(index: number) {
dispatch({
type: 'HIDE_TOAST',
payload: index
});
}
useEffect(() => {
let timeoutIds = [];
state.toasts.forEach((_, index) => {
timeoutIds[index] = setTimeout(() => hideToast(index), 3000);
});
return () => timeoutIds.forEach(timeoutId => clearTimeout(timeoutId));
}, [state.toasts]);
return {
toasts: state.toasts,
showToast,
hideToast
};
}
function App() {
const { toasts, showToast, hideToast } = useToast();
return (
<div>
{toasts.map((toast, index) => (
<div
className={`toast toast-${toast.type}`}
key={index}
>
<p>{toast.msg}</p>
<button onClick={() => hideToast(index)}>Close</button>
</div>
))}
<button onClick={() => showToast('This is a success toast!', 'success')}>
Show Success Toast
</button>
<button onClick={() => showToast('This is an error toast!', 'error')}>
Show Error Toast
</button>
</div>
);
}
In this example, the code is written in TypeScript, and type annotations have been added to the functions and variables to specify the types of their arguments and return values. This allows the TypeScript compiler to check the code for type errors, and provides additional type information to other tools and libraries that can make use of it. You can modify this example further to suit your specific needs, such as adding additional types or using more advanced type features.
Next, can it refactor this?
Could we refactor this?
Yes, it is possible to refactor the code to make it more concise and modular. Here is an example of how you might do this:
import React, { useReducer, useEffect } from 'react';
interface Toast {
msg: string;
type: string;
}
type State = Toast[];
type Action =
| { type: 'SHOW_TOAST'; payload: Toast }
| { type: 'HIDE_TOAST'; payload: number };
const initialState: State = [];
function reducer(state: State, action: Action): State {
switch (action.type) {
case 'SHOW_TOAST':
return [...state, action.payload];
case 'HIDE_TOAST':
const newToasts = [...state];
newToasts.splice(action.payload, 1);
return newToasts;
default:
return state;
}
}
function useToast() {
const [toasts, dispatch] = useReducer(reducer, initialState);
useEffect(() => {
const timeoutIds = toasts.map((_, index) =>
setTimeout(() => dispatch({ type: 'HIDE_TOAST', payload: index }), 3000)
);
return () => timeoutIds.forEach(clearTimeout);
}, [toasts]);
return {
toasts,
showToast: (msg: string, type: string) =>
dispatch({ type: 'SHOW_TOAST', payload: { msg, type } }),
hideToast: (index: number) =>
dispatch({ type: 'HIDE_TOAST', payload: index })
};
}
function App() {
const { toasts, showToast, hideToast } = useToast();
return (
<div>
{toasts.map((toast, index) => (
<div
className={`toast toast-${toast.type}`}
key={index}
>
<p>{toast.msg}</p>
<button onClick={() => hideToast(index)}>Close</button>
</div>
))}
<button onClick={() => showToast('This is a success toast!', 'success')}>
Show Success Toast
</button>
<button onClick={() => showToast('This is an error toast!', 'error')}>
Show Error Toast
</button>
</div>
);
}
In this example, the code has been refactored to use more concise and modular functions and types. The reducer function has been simplified and made more type-safe by using a union type for the
Actiontype, and theuseToasthook has been refactored to use the useReducer hook more effectively and efficiently. Additionally, the code has been cleaned up and made more readable by using modern JavaScript features and conventions. You can modify this example further to suit your specific
Great. Now, we should really write a test for this. Let's see if ChatGPT can do that for us:
How might we test this hook with Jest?
To test the
useToasthook with Jest, you can write a test that uses the act function from the@testing-library/reactlibrary to simulate user interactions with the component and verify that the hook behaves as expected. Here is an example of how you might write a test for theuseToasthook:
import React from 'react';
import { act, renderHook } from '@testing-library/react-hooks';
import { useToast } from './useToast';
describe('useToast', () => {
it('should show and hide toasts', () => {
const { result } = renderHook(() => useToast());
const { toasts, showToast, hideToast } = result.current;
// Initially, there should be no toasts
expect(toasts).toEqual([]);
// Show a toast and verify that it appears in the state
act(() => showToast('This is a test toast', 'success'));
expect(toasts).toEqual([{ msg: 'This is a test toast', type: 'success' }]);
// Hide the toast and verify that it disappears from the state
act(() => hideToast(0));
expect(toasts).toEqual([]);
});
});
In this test, the
renderHookfunction from the@testing-library/react-hookslibrary is used to render theuseToasthook in a test environment. The test then simulates user interactions with the hook by calling theshowToastandhideToastfunctions, and verifies that the toasts are shown and hidden as expected. This test can be further extended to cover additional scenarios and edge cases, such as showing multiple toasts at once or verifying the behavior of the hook when an error occurs.
Overall, this looks pretty good! I'd need to spend a lot more time than I can spare now to try to find if there are any issues with it, and it wouldn't surprise me if there were a few bugs, but it looks fairly sounds as an example.
Another thing that ChatGPT seems useful for is creating examples. For instance, I've never had the occasion to use render props in React, so I asked ChatGPT the following question:
Please demonstrate the use of render props with functional React components
Sure! In React, a "render prop" is a technique for sharing code between React components using a prop whose value is a function. This function is used to render the content of the component. Using a render prop with a functional component is no different than using it with a class-based component. Here's an example:
function MyComponent(props) {
return (
<div>
{props.render(props.value)}
</div>
);
}
In the above example, MyComponent is a functional component that has a render prop, which is a function that is used to render the content of the component. The render prop takes a value prop as an argument, which can be used in the rendering of the content.
Here's an example of how you might use this component:
<MyComponent
value={5}
render={value => (
<div>
The value is {value}.
</div>
)}
/>
In this example, the value passed to the value prop is 5, and the render prop is a function that returns a div element with the text "The value is 5".
In summary, using a render prop with a functional component is just a matter of using a prop whose value is a function, and using that function to render the content of the component.
I personally find this is a better, more concise example than the one in the React documentation, so I'm quite pleased with that as an example. Now let's ask for them in Typescript:
Please convert these examples to Typescript
Sure, here are the examples written in TypeScript:
function MyComponent(props: { value: any; render: (value: any) => React.ReactNode }) {
return (
<div>
{props.render(props.value)}
</div>
);
}
<MyComponent
value={5}
render={(value: any) => (
<div>
The value is {value}.
</div>
)}
/>
In the first example, the MyComponent function is defined to take an object with two properties: value and render. The value property is of type any, which means it can be any value. The render property is a function that takes a value of type any and returns a React.ReactNode, which is the type of value that can be rendered by a React component.
In the second example, the value prop is passed the value 5, which is a number. The render prop is passed a function that takes a value of type any and returns a div element.
I hope this helps! Let me know if you have any other questions.
Nice one!
I thought I'd try another example that was more immediately useful to me. I work on a large legacy Zend 1 framework which I'm slowly trying to modernize, and a big chunk of the models have been migrated to Eloquent, but the controllers are the biggest blocker by far to migrating to a newer framework, and as long as they're in use we can't migrate easily migrate some other parts, such as the forms. I wrote an example Zend 1 controller and asked ChatGPT the following question:
Given the following Zend 1 controller:
<?php
use App\Forms\CategoryForm;
use App\Models\Category;
final class CategoriesController extends Zend_Controller_Action
{
public function indexAction(): void
{
$this->view->categories = Category::all();
}
public function addAction(): void
{
$request = $this->getRequest();
assert($request instanceof Zend_Http_Request_Http);
if (!$request->isPost()) {
throw new Zend_Controller_Action_Exception("Unsupported method", 405);
}
$form = new CategoryForm();
if (!$form->isValid($request->getPost())) {
throw new Zend_Controller_Action_Exception("Invalid data", 422);
}
$category = Category::create([
'name' => $form->name->getValue(),
]);
$this->view->category = $category;
}
}
Please convert it to a Laravel controller
It came back with:
Here is a possible conversion of the given Zend 1 controller to a Laravel controller:
<?php
use App\Http\Controllers\Controller;
use App\Forms\CategoryForm;
use App\Models\Category;
use Illuminate\Http\Request;
class CategoriesController extends Controller
{
public function index(): void
{
$categories = Category::all();
return view('categories.index', compact('categories'));
}
public function add(Request $request): void
{
if (!$request->isMethod('post')) {
abort(405, 'Unsupported method');
}
$form = new CategoryForm();
if (!$form->isValid($request->all())) {
abort(422, 'Invalid data');
}
$category = Category::create([
'name' => $form->name->getValue(),
]);
return view('categories.add', compact('category'));
}
}
Note that this is just one possible way to convert the given code, and there may be other ways to accomplish the same thing using Laravel's features and conventions.
This looks pretty good to me. It does still depend on the Zend form classes, but once the controller has been rewritten for Laravel, it would be easy to replace them with form request classes. While this is a very minimal example, it shows the potential power of ChatGPT in terms of migrating legacy code to more modern frameworks. I'm sure it's not always going to be 100% accurate, but other tools like Psalm, which I use anyway, will help find potential problems with method names or arguments being wrong, as will peer reviews of the code, and it'd certainly be less laborious than doing it all manually.
I asked it the following question:
Write the homepage copy for a website proving tips and tricks with performance improvements for web applications built with Laravel
And it came back with:
Welcome to Tips and Tricks for Laravel Performance!
Are you looking to improve the performance of your web application built with Laravel? You've come to the right place!
Our website provides a wealth of information and tips on how to optimize your Laravel application for maximum performance. From caching and database optimization, to code refactoring and route optimization, we've got you covered.
We also offer in-depth tutorials and guides on how to implement these performance improvements in your own Laravel application.
Don't let slow performance hold your web application back. Take control and improve your Laravel application's performance today with the help of Tips and Tricks for Laravel Performance.
Not bad, I've certainly seen a lot worse than that from human writers. Next, I asked it to write a blog post for the site:
Now write a blog post for this site on how to improve the performance of the site by setting appropriate HTTP headers, with code samples
Improving the performance of your Laravel application starts with understanding the role of HTTP headers. HTTP headers are key-value pairs that are sent in the header of an HTTP request or response, and provide important information about the request or response.
One of the ways to improve the performance of your Laravel application is to set appropriate HTTP headers. This allows the client, such as a web browser, to make more informed decisions about how to handle the request or response.
For example, setting the Cache-Control header can improve performance by allowing the client to cache the response, so that it doesn't have to be fetched again on subsequent requests. This can be done in Laravel using the Response facade:
use Illuminate\Support\Facades\Response;
// Set the Cache-Control header to cache the response for 1 hour
Response::header('Cache-Control', 'max-age=3600');
Another important header for improving performance is the Expires header. This header specifies a date and time at which the response will no longer be considered fresh. This allows the client to make an informed decision about whether to use a cached version of the response or fetch a new one.
In Laravel, the Expires header can be set using the Response facade:
use Carbon\Carbon;
use Illuminate\Support\Facades\Response;
// Set the Expires header to one hour from now
$expires = Carbon::now()->addHour();
Response::header('Expires', $expires->toRfc2822String());
By setting these headers, you can improve the performance of your Laravel application by allowing the client to make more efficient use of caching. This can reduce the number of requests that need to be made to the server, resulting in faster load times and a better user experience.
Of course, there are many other HTTP headers that can be used to improve the performance of your Laravel application. For more information, check out the official Laravel documentation on HTTP headers.
Not hugely comprehensive, but a reasonably good starting point. Using this to get you started seems like a good idea, and there's nothing more intimidating than a blank page when you want to write a blog post.
Even in its current state as a tech preview, ChatGPT is hugely impressive. It's extraordinary how good it is at generating basic code samples for almost any use case I can think of. However, the distinct impression I get is that it's not really capable of original thought. Most of the above is basically just taking stuff that's already out there and essentially remixing it. There's plenty of tutorials on writing all of the above and it looks to me like it's just taking those and converting those according to the provided specifications.
However, don't get the impression that doesn't make it useful. I've used Github Copilot for a while and that offers dramatic improvements in productivity, and this has the potential to be much more significant. As shown above, it can migrate a simple controller from Zend 1 to Laravel, with the result looking perfectly acceptable, and the value of that should be clear to anyone who has to work on a large legacy project. Similarly you can ask it to rewrite something to use a specific design pattern and the end result is perfectly acceptable. It's a fantastic learning tool too since you can ask it to provide an example specific to your use case rather than trawling through blog posts, where most of them might have different requirements to you. As such it's going to hugely improve developer productivity.
To a large extent, I think something like this is going change the developer's role by shifting the emphasis of it somewhat from the productive to the executive, with our job being more akin to editors than authors. Coding will become less about solving the problem and more about defining the problem in the first place and letting the system solve it. However, I don't think it will automate our jobs away entirely - the quality of the code it produces is variable, to say the least, and there will definitely be a need to be able to debug it, and solve more unusual problems.
However, if my job involved writing spammy blog posts for ad money, I'd be very worried about my future prospects. I think tools like this will probably be writing most of the spammier sort of blog posts that just exist to get clicks on the web in a year at most. I've actually just asked it to write a blog post I've wanted to write for a while now for me, and the end result looks pretty solid right now - I'd anticipate it saved me about 90% of the work, with the remaining 10% just a case of cleaning it up.
]]>I quite quickly embraced this concept, and began routinely using the repository pattern as a matter of course on new projects. Yet nowadays, I've largely stopped using the repository pattern, because experience has taught me that it's really not all it's cracked up to be. It often adds very little value for a lot of effort, and I really don't think it's often worthwhile. Here I'll break down the reasons I no longer use it.
Out of the box, Eloquent supports SQLite, MySQL/MariaDB, PostgreSQL and MSSQL. It is a somewhat leaky abstraction, but that can't be helped, and as Martin Fowler said, that isn't a reason to avoid them. Mapping relational data to object oriented code is hard, and if you expect your ORM to completely abstract away the difference between relational databases, then your expectations are unreasonable. ORMs cover the 90% use cases very well, which makes a lot of stuff significantly easier, and offer escape hatches for when you need them. Unless you have a really good reason not to, you should be using the default ORM provided by your framework, and the onus is on you to justify not doing so if you feel it makes sense.
Furthermore, it's possible to extend Eloquent to support various non-relational data backends such as:
If you really need to rewrite an existing application to support a whole new database backend that isn't supported out of the box by Eloquent, or by an off-the-shelf package, then ultimately you could consider writing your own Eloquent extension to facilitate this. But I'd be very surprised if that happens often.
If you're building an application that uses a relational database, then it's likely that most of the data you are storing is fairly well-suited to a relational data model (if it wasn't, why would you be using a relational model now?). As such, it's decidedly unlikely that you're ever going to need to migrate it to a non-relational database store, unless something fairly fundamental changes. Building out repositories on the offchance you might one day need to migrate to a database backend not supported by Eloquent, or to a database interface other than Eloquent, is probably excessive, and unless you have a very specific use case, a violation of the YAGNI principle.
I'm not going to pretend my own experience is necessarily representative of every possible experience (nor should you insinuate the same), but I've been in the industry since 2011, and the only time I've ever had to migrate a website from one database engine to another was with a legacy Zend 1 application that takes up a lot of my time at work. That had been on the same server since around 2010, despite a rather shaky rewrite in 2015 before I got there, and was still using MySQL 5.0, and PHP 5.4. It became necessary to move it to a new server, and it wasn't possible (or desirable) to install a version of MySQL that old on the new server. As such I took the decision that we needed to bite the bullet and migrate to a currently supported database, despite the potential issues it could cause. Given there were inevitably going to be teething troubles when migrating a large, very legacy application with no tests, but that most of the existing queries were not very sophisticated, then migrating to MariaDB 10.2 would be no harder than migrating to MySQL 5.7, so I opted for the former. While this did cause some grief (particularly with respect to boolean fields), it used the same Zend 1 database layer, built on top of PDO, despite migrating to a different version of a different database (albeit a fork of the original).
And if the problem is that the amount of data means that queries are taking too long, it could easily be simply that there aren't appropriate indexes set up, as memorably demonstrated in Commitstrip.
This is an edge case that's probably not worth even thinking about. The only circumstances under which you might be confronted with an explicit need to migrate away from Eloquent are the following:
I've been in the situation on the aforementioned legacy project of migrating from Zend 1 DB to Eloquent, and it really isn't that big a deal to do so because all these query builders and database interfaces do largely the same thing - there are some implementation details that differ, but they're never all that different, and where you're using database-specific functionality then you're likely using one of the escape hatches to write raw SQL anyway. The only problems I've encountered are down to the original developer rolling their own crappy legacy models, not to the underlying queries.
And if you're planning on migrating away from Eloquent to raw database queries, just because someone told you it's faster, don't.
If you do determine that you need to switch part of your application to a different database engine, it's very unlikely that the whole database needs to be replaced lock, stock and barrel. Most likely, it'll be a handful of tables that are a better fit for a different data store. Under these circumstances, why would you want to move other tables, which are a good fit for the relational model, to a different database, and potentially degrade performance?
Most likely, what you'll end up with is a hybrid model where most of your data is relational and is stored in something Eloquent can work with, while the other data which is a better fit for a different data store is handled by an alternative backend. That limits the scope of any changes you need to make to just those queries that touch on the table you plan to migrate. And as stated above, implementing that on the offchance you may need it in future is a violation of YAGNI.
And if the reason for switching is due to the sheer size of the data, different tables will likely reach that point at different times, so you can migrate each one to the new store at the point it starts to become an issue.
It used to be the case that storing arbitrary keys and values in a relational database was tricky, and you had to resort to sub-optimal solutions such as Entity-Attribute-Value, as used by, for example, the WordPress wp_postmeta table. At that time, a relational database such as MongoDB offered a significant advantages in terms of being able to store arbitrary data.
Since then, most relational databases have introduced new field types such as HStoreField or JSON field types, which allow for easily storing arbitrary keys and values within a row of a relational database, and ORMs such as Eloquent allow for casting that data to a convenient form. As such, that particular use case for a non-relational database over a relational one is now largely redundant. It's also possible to enforce a JSON schema so that you can exercise as much or as little control over the data as necessary.
There are other use cases for non-relational databases, but most of those only really come into play when you have truly colossal amounts of data, and to be honest it takes a long time to get to that point. If you get to the point where you need to worry about those kind of issues, you can probably afford to deal with it.
Writing a repository class for all the models you plan to use in an application is something not to be taken lightly. You have to collect every query you're ever going to make against a specific table and place it in one class, and for a large application that will be a lot of work. Yes, there will be some common methods that can live in a base class, such as ones for all items, items by ID, paginated list etc, but there will still be a lot of work involved, and it will likely be quite repetitive, with some differing only slightly.
And if you're also planning to decorate the repositories to be able to cache them, the burden increases significantly. For each model, you need an interface for the repository, a class for the repository implementation, and a class for the decorator, as well as all the boilerplate to resolve the interface correctly.
Honestly, this is probably the biggest issue for me these days. I routinely use Psalm on my projects these days, and it's been hugely beneficial to those projects to have that kind of feedback about how well-typed my code is. Abstracting away the difference between queries when using different repository implementations means we can't return ORM-specific objects, leaving us with two alternatives:
Neither of these options are great. The first one reduces the type safety of the application substantially, and the second will cause you an awful lot of work for very little benefit. I would definitely struggle to justify this to my bosses or clients.
A big part of the promise of the repository pattern is being able to run unit tests without hitting the database. The trouble is that a database is an integral part of your application, and replacing it with mocks often isn't very useful. Mocks are only as good as the data they provide, and if your mock data diverges from what the database actually provides, it's easy for issues to slip through without being caught by your tests.
As long as you have migrations that can recreate the structure of your database accurately (if not the content), then you can happily use an in-memory SQLite database as an alternative to your production database for most functionality that isn't database-specific. That's not to say it's always a drop-in replacement for your production database, and you should be aware of the possibility of differences in behaviour between databases if you're using something else in production, but it's a damn sight closer to MySQL in behaviour than mocking out the query. Often, a good compromise is to use an in-memory SQLite database for testing locally, where it's more important to be able to run tests quickly, but use your production database engine in continuous integration where it's more important for everything to be correct. If you're building a generic package where it needs to support every database engine supported by Eloquent, then your continuous integration solution should of course actively test against every supported database engine.
If there are use cases where you need to use functionality from MySQL or PostgreSQL that doesn't exist in SQLite in tests, James Bannister suggested a way to patch missing functions that can help.
Repositories are generally a better fit for a DataMapper-style ORM than ActiveRecord, and many actually include a repository implementation by default, eg Doctrine. This isn't a criticism of ActiveRecord, which is a simple, intuitive way of building an ORM, and is implemented by many other frameworks too (Django is a good example), but sometimes it's just not a good fit for your application.
If you really need the specific advantages of the repository pattern, then trying to retrofit it to an ActiveRecord-style ORM like Eloquent from the outset is an awful lot of work. There's a Doctrine integration for Laravel and you're far better off just using that, rather than trying to wrap your own implementation around Eloquent. Almost invariably, your own implementation will be crappier than that, and involve a lot more work, so why waste time and effort on it?
I haven't completely stopped using the repository pattern. What I tend to do nowadays is as follows:
Page::find($id), or a slightly more complex query that's used only in one place.scopeIsInDate() to retrieve only items which are in date.UNION across those subqueries, so they require a lot of repetitive queries. Long-term the solution would be to refactor those tables down to a single table for the various content types, but that's not going to be practical any time soon.That said, the work I do now is different - I used to build APIs for mobile apps where the endpoints were generally generic endpoints that exposed CRUD functionality for different types of resources. It's been a while since I've done that, and the repository pattern would arguably provide more benefit for that kind of functionality where most of the queries were things like "get this resource by ID", "get paginated list of these resources" etc.
]]>If you're not familiar with the idea, consider this class:
<?php
declare(strict_types=1);
namespace App\Jobs;
use Illuminate\Database\ConnectionInterface;
use Illuminate\Support\Benchmark;
final class Printer
{
public function __invoke(string $value): void
{
echo $value;
}
}
Note the use of the __invoke() magic method. This gets called if you try to call the object as a function, eg:
<?php
// Will echo "Hello, World!"
$printer = new Printer();
$printer("Hello, World!");
Now, this may not seem like a terribly big deal, but it's only once you start putting them together that their real power becomes apparent. They're essentially "closures on steroids" in that they can do basically anything a closure can, and a lot of stuff they can't:
callable type hint, so you can generally use it in most of the same places you would a closure. As such, if you have a closure whose functionality needs to be reused elsewhere, it may make sense to refactor it into an invokable class.As such, invokables let you chain functionality in the same way you would with closures, but with more capabilities and a higher level of abstraction. For instance, imagine you work on an e-commerce application, where each order is represented by an ORM model called Order, and the job to process an order is implemented in an invokable class called ProcessOrder, which accepts an instance of Order. Now, imagine a third party want to place multiple orders by sending a CSV file over FTP. Because you implemented ProcessOrder as an invokable, all you need to do is get the CSV data, generate an instance of Order from each row, and pass it into ProcessOrder, without changing a single existing line of code. You might do something like this:
<?php
$data = file_get_contents($remote_url);
$result = Collection::make($data)
->map(App::make(ConvertToOrder::class))
->each(App::make(ProcessOrder::class));
All ConvertToOrder has to do is take the array data and create the model instance, then pass it on. Orders are processed consistently between those on the e-commerce site and those received via FTP, and the amount of new code required is minimal, limited to the ConvertToOrder class and whatever command class is being triggered (in this case, it might be an Artisan command). As long as you've picked an appropriate name for each class, it's really obvious how this pipeline works and what each step does, without the developer having to even open the class in question.
Using __invoke() as the defined method for doing something when the class only carries out a single action also makes sense as a general convention. If the class name, by itself, defines what the class is meant to do, then a method name is largely superfluous, and you end up making your method something like process(), execute() or handle(). Using __invoke() instead is both more concise and more consistent, because it allows you to use the shorter syntax, without the need to either choose or remember an actual method name.
Assuming you're working with a framework like Laravel, then as long as you're working on a class that's not one of the class types explicitly required by the framework, then you should be fine to use invokables however you like. For instance, if you have something like the ProcessOrder service class above, then its only real dependency on Laravel itself would be that it takes in an ORM instance, plus whatever is pulled in via constructor injection. However, classes generated by the framework itself are more dependent on a particular, predefined structure. That said, there are some parts of the framework that are amenable to using invokables.
For a while now, Laravel has supported single action controllers, which implement a single __invoke() method, as in this example:
<?php
declare(strict_types=1);
namespace App\Http\Controllers;
use App\Models\User;
final class FooController extends Controller
{
/**
* Return a view
*
* @return \Illuminate\Http\Response
*/
public function __invoke()
{
return view('foo');
}
}
This has the following advantages:
Using callables as controllers doesn't make sense for every use case. For instance, if you're building an API that exposes CRUD functionality for multiple resource types, it probably makes more sense to use a resource controller which defines all the actions for a given resource type, particularly if they're similar enough that you're extending a base resource controller with common functionality. But for any reasonably complex route, it may make sense to use a single action controller.
Middleware is something else that only really has one public method and could therefore be implemented as an invokable, at least in theory. Some frameworks, such as Laminas, explicitly support it. The Laravel documentation doesn't appear to mention it, but after some experimentation I've discovered that it's possible to use callables as middleware in Laravel. For instance, take this callable middleware class I wrote:
<?php
declare(strict_types=1);
namespace App\Http\Middleware;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
final class CallableDemo
{
public function __invoke(Request $request, $next): Response
{
$response = $next($request);
$response->header('X-Clacks-Overhead', 'GNU Terry Pratchett');
return $response;
}
}
This is a relatively simple middleware class which adds the X-Clacks-Overhead header to the response. At least in a recent version of Laravel 9, the following method of adding middleware in the router works:
<?php
...
use App\Http\Middleware\CallableDemo;
...
Route::resource('foo', FooController::class)
->middleware(CallableDemo::class);
As does declaring it as global middleware in app\Http\Kernel.php:
<?php
namespace App\Http;
...
class Kernel extends HttpKernel
{
protected $middleware = [
...
\App\Http\Middleware\CallableDemo::class,
];
Or in the web group:
<?php
...
/**
* The application's route middleware groups.
*
* @var array<string, array<int, class-string|string>>
*/
protected $middlewareGroups = [
'web' => [
...
\App\Http\Middleware\CallableDemo::class,
],
Or as route middleware:
<?php
protected $routeMiddleware = [
...
'gnu' => \App\Http\Middleware\CallableDemo::class,
];
This example doesn't cover middleware that accepts dependencies from the container, however. So what if we amend our middleware class to accept a raw database connection as a constructor dependency and use that in the middleware body to add a header giving the total number of users, as in this example?
<?php
declare(strict_types=1);
namespace App\Http\Middleware;
use Illuminate\Database\ConnectionInterface;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
final class CallableDemo
{
public function __construct(private ConnectionInterface $db)
{
}
public function __invoke(Request $request, $next): Response
{
$response = $next($request);
$response->header('X-Clacks-Overhead', 'GNU Terry Pratchett');
$response->header('X-Total-Users', $this->db->table('users')->count());
return $response;
}
}
Yes, looks like this works fine too.
Job classes are something else that do only one thing, and thus it potentially makes sense to use an invokable class for them. Consider this job class which uses the Benchmark helper to benchmark a query and dump the results to the screen:
<?php
declare(strict_types=1);
namespace App\Jobs;
use Illuminate\Database\ConnectionInterface;
use Illuminate\Support\Benchmark;
final class ThingDoer
{
public function __construct(private ConnectionInterface $db)
{
}
public function __invoke()
{
Benchmark::dd(fn() => $this->db->table('users')->get());
}
}
If we try the following in a route closure:
Route::get('/', function () {
dispatch(ThingDoer::class);
We see the error get_class(): Argument #1 ($object) must be of type object, string given. So instead, we need to fetch ThingDoer from the container and pass it to dispatch():
Route::get('/', function (ThingDoer $doer) {
dispatch($doer);
In a controller, it may well make more sense to do this via method injection.
Event listeners are yet another example of something that only really does one thing. This invokable listener is based on the one used to send notifications in Laravel Bootcamp:
<?php
namespace App\Listeners;
use App\Events\ChirpCreated;
use App\Models\User;
use App\Notifications\NewChirp;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
class SendChirpCreatedNotifications implements ShouldQueue
{
/**
* Create the event listener.
*
* @return void
*/
public function __construct()
{
//
}
/**
* Handle the event.
*
* @param \App\Events\ChirpCreated $event
* @return void
*/
public function __invoke(ChirpCreated $event)
{
foreach (User::cursor() as $user) {
$user->notify(new NewChirp($event->chirp));
}
}
}
This works in exactly the same way as a standard listener class. If you map it to an event class in the usual way, it works entirely as expected. However, as with some of the other examples, it's not clear if it supports constructor injection, so it's best to check. If we amend the listener as follows:
<?php
namespace App\Listeners;
use App\Events\ChirpCreated;
use App\Models\User;
use App\Notifications\NewChirp;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Database\ConnectionInterface;
use Illuminate\Queue\InteractsWithQueue;
class SendChirpCreatedNotifications implements ShouldQueue
{
/**
* Create the event listener.
*
* @return void
*/
public function __construct(private ConnectionInterface $db)
{
}
/**
* Handle the event.
*
* @param \App\Events\ChirpCreated $event
* @return void
*/
public function __invoke(ChirpCreated $event)
{
foreach ($this->db->table('users')->cursor() as $user) {
dd($user);
}
}
}
Now, if we trigger the ChirpCreated event, it breaks at the right point and spits out the user data as expected, thus demonstrating that it works.
There are some limitations of using invokable classes which you should bear in mind when deciding whether to make a class an invokable or not. For instance, accessing an invokable as as property of another class can be awkward - take this controller class:
<?php
namespace AppServiceProvider
use App\Jobs\ThingDoer;
final class FooController extends Controller
{
public function __construct(private ThingDoer $thingDoer)
{
}
/**
* Return a view
*
* @return \Illuminate\Http\Response
*/
public function __invoke()
{
// Call $this->thingDoer...
return view('foo');
}
}
We can't call $this->thingDoer() because $this refers to the instance of FooController, and so we're referring to a non-existing method of FooController called thingDoer rather than the property $this->thingDoer. There are a couple of ways to do it. You can call __invoke() explicitly, which isn't very elegant:
<?php
final class FooController extends Controller
{
...
/**
* Return a view
*
* @return \Illuminate\Http\Response
*/
public function __invoke()
{
$this->thingDoer->__invoke();
return view('foo');
}
}
Or you can use call_user_func():
<?php
final class FooController extends Controller
{
...
/**
* Return a view
*
* @return \Illuminate\Http\Response
*/
public function __invoke()
{
call_user_func($this->thingDoer);
return view('foo');
}
}
Or, my personal favourite approach:
<?php
final class FooController extends Controller
{
...
/**
* Return a view
*
* @return \Illuminate\Http\Response
*/
public function __invoke()
{
($this->thingDoer)();
return view('foo');
}
}
In the context of Laravel controllers, you also have the option to use method injection:
<?php
final class FooController extends Controller
{
...
/**
* Return a view
*
* @return \Illuminate\Http\Response
*/
public function __invoke(ThingDoer $thingDoer)
{
$thingDoer();
return view('foo');
}
}
Using invokable classes for any part of your application that does one thing only, and could potentially be reused, makes a lot of sense. It allows for more elegant code, giving you the advantages of functional programming without losing the benefits of OOP, and allows you to break your application down into a selection of easily reusable parts. While I've not been in a position to try it before, I also suspect that it makes decorating components simpler, to the point that certain tasks like logging and caching can be done with a single closure or invokable. Next time you write a class to do something, give serious thought to the idea of whether it should be an invokable - the answer may be "yes" more often than you think, and it'll often help make your code simpler and more reusable.
]]>A lot of people seem to think that using an ORM inherently makes your application perform badly. However, this just isn't true, as long as you're using the ORM the right way. Using an ORM not only allows you to solve certain classes of performance problems more easily than by writing SQL statements, but they generally make it easier to reason about how your application works. However, there are some things you need to bear in mind when using one, to prevent you from introducing potential performance problems. In this post, I'll give you the reasons why you should consider using an ORM on your projects, at least by default, and warn you about some of the things that can cause trouble when using one.
If you're going to patronize me, or other commenters, by mansplaining ActiveRecord vs DataMapper, you can get in the damned sea. I know the difference and I've chosen to use ActiveRecord. I'm categorically not interested in rehashing that argument, let alone being condescended to, and I will delete any comments that I think do either. If you do have legitimate, specific gripes about Eloquent, or any other implementation of ActiveRecord, or indeed ORMs in general, and can moan about them without being unpleasant to other people, I'm happy to accept those comments. No tool is perfect, and there are always some cases where it will cause problems, but I will not tolerate anyone being disrespectful. Using Laravel, Eloquent, or any ActiveRecord implementation, does not make someone Nooby McNoobface, and if you're going to claim it does, you're not welcome here.
Please note, that while I'm referring to Eloquent throughout this post, the overwhelming majority of what I'm talking about is also applicable to other ORMs, particularly other Active Record-style ORMs such as the Django ORM. I'm using Eloquent as the primary example here because it's the one I've used most often in the last few years.
Below I've listed the reasons I can think of for using an ORM. I don't think this is necessarily an exhaustive list, and others may be able to think of others or express these reasons more elegantly than I can. If you can think of other good reasons, feel free to add them to the comments.
In my experience, N+1 queries are far and away the most common performance problem I've encountered when dealing with legacy applications that don't use an ORM. They're typically somewhat less obvious than a single slow query would be when profiling your code because the problem comes from multiple small queries, rather than from single large ones, but they can have a crippling effect on the performance of your application.
It is possible to use JOINs to pull in another table and get the related data in a single query, but that really starts to get hairy if you have to pull in multiple levels of tables, and it can be very difficult to write a query that does so while remaining easy to understand.
Fortunately, most ORMs have simple methods for efficiently fetching related data via eager loading. For instance, Eloquent has the with() and load() methods. By making good use of these methods, you can write efficient queries that are still straightforward to understand. In addition, you can also use methods such as has() and whereHas() to query relationship existence, which is generally a lot more elegant than the underlying WHERE EXISTS statement.
Eloquent also carries out a degree of caching, particularly when dealing with relations. This can sometimes eliminate queries that would be made by a more naive ORM, but in the event you do need it, you can call the refresh() method on the model to ensure it's up to date.
Using an ORM, as opposed to a query builder or writing raw SQL, offers significant advantages in terms of the type safety of the code base.
For instance, say you have the below method in a Laravel project which returns an array of data from a query:
<?php
use DB;
final class ProductRepository {
// Rest of class...
public function getFirstProductBelow(float $price): array
{
return DB::table('products')->where('price', '<', $price)->first();
}
}
While having a return type at all is better than none, it isn't very useful for static analysis tools. Just telling Psalm that the response is an array doesn't tell it what fields to expect in that array.
You can use annotations to specify a more meaningful response...
<?php
use DB;
final class ProductRepository {
// Rest of class...
/*
* @psalm-return array{id: int, name: string, price: float}
*/
public function getFirstProductBelow(float $price): array
{
return DB::table('products')->where('price', '<', $price)->first();
}
}
And that would tell Psalm that it returns an array with the denoted keys. However, it's not the best solution:
@psalm-return docblock to any other method that returns a list of those items, in which case adding a new field becomes problematic, or you'd have to use a predefined template annotationassert() calls about the shape of the array, we can't validate that the right values exist.But suppose we instead use Eloquent. Our method might then look like this:
<?php
use App\Models\Product;
final class ProductRepository {
// Rest of class...
public function getFirstProductBelow(float $price): Product
{
return Product::where('price', '<', $price)->first();
}
}
We now know with absolute certainty that the response from this method is an instance of App\Models\Product because we've been able to declare a return type, and if it wasn't, the method would throw an exception.
By itself, that doesn't tell us what fields to expect on an instance of App\Models\Product, but Laravel IDE Helper can easily generate suitable @property annotations for us, based on the current database structure. If we run the following command:
$ php artisan ide-helper:models -W
Then our model might end up looking something like this:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
/*
* @property integer $id
* @property string $name
* @property float price
*/
final class Product extends Model
{
// class body here
}
And that gives Psalm a single, canonical description of the structure of this class. Even if you couldn't use Laravel IDE Helper for some reason, it's not exactly onerous to manually define the properties on a given model in one place - it's the work of a few minutes if you do it at the same time you define your models and migrations.
For even better type safety on your models, you can add the @psalm-seal-properties annotation, which will ensure that if you try to use an undocumented property on the model, Psalm will flag it as an issue. And having comprehensive type information isn't just a matter of finding type issues, it also affects how good your autocompletion will be - with better type hints, you'll have more effective and accurate completion options.
I maintain a large legacy Zend 1 application where the original developer decided they didn't want to use an existing ORM. Instead, they wrote their own model classes which looked something like this:
<?php
class Application_Model_Page
{
protected $id;
protected $name;
protected $price;
public function __construct()
{
$this->id = null;
$this->name = null;
$this->price = null;
}
public function getId()
{
return $this->id;
}
public function setId($val)
{
$this->id = $val;
return $this;
}
public function getName()
{
return $this->name;
}
public function setName($val)
{
$this->name = $val;
return $this;
}
public function getPrice()
{
return $this->price;
}
public function setPrice($val)
{
$this->price = $val;
return $this;
}
public function toArray()
{
return [
'id' => $this->id,
'name' => $this->name,
'price' => $this->price,
];
}
public function populate(array $data)
{
$this->id = $data['id'];
$this->name = $data['name'];
$this->price = $data['price'];
return $this;
}
public function save()
{
$db = Zend_Registry::get('db');
$data = [
'name' => $this->name,
'price' => $this->price,
];
$db->update('products', $data, 'id=' . $this->id);
}
public function find($id)
{
$db = Zend_Registry::get('db');
$result = $db->fetchRow('SELECT * FROM products WHERE id = ' . $id);
return $this->populate($result);
}
}
Honestly, there are so many issues with this it's hard to know where to start:
find() method requires that you first create an instance of the object, then call that method to return another instance, eg (new Application_Model_Page())->find(1), which is extremely cumbersome<?php
$response = [];
foreach ($result as $row) {
$response[] = (new Application_Model_Page())->populate($row);
}
return $response;
We're in the process of migrating off these legacy models to Eloquent, with the intent of eventually migrating the whole application to Laravel, and the contrast between using the two model types could not be greater. The Eloquent models are easy to maintain, easy to work with, highly performant, and require far less boilerplate code when implementing functionality.
Martin Fowler covered this issue pretty well in ORM Hate. To quote:
Listening to some critics, you'd think that the best thing for a modern software developer to do is roll their own ORM. The implication is that tools like Hibernate and Active Record have just become bloatware, so you should come up with your own lightweight alternative. Now I've spent many an hour griping at bloatware, but ORMs really don't fit the bill - and I say this with bitter memory. For much of the 90's I saw project after project deal with the object/relational mapping problem by writing their own framework - it was always much tougher than people imagined. Usually you'd get enough early success to commit deeply to the framework and only after a while did you realize you were in a quagmire - this is where I sympathize greatly with Ted Neward's famous quote that object-relational mapping is the Vietnam of Computer Science.
The widely available open source ORMs (such as iBatis, Hibernate, and Active Record) did a great deal to remove this problem. Certainly they are not trivial tools to use, as I said the underlying problem is hard, but you don't have to deal with the full experience of writing that stuff (the horror, the horror). However much you may hate using an ORM, take my word for it - you're better off.
And it's worth bearing in mind that those words were written a decade ago. We now have over ten years' more experience finding potential problems with ORMs and finding effective solutions for those problems, and Eloquent has benefited from those changes, as well as improvements in the PHP language. Many issues you might have with an ORM ten years ago may simply no longer be worth worrying about.
Eloquent's scopes in particular have been invaluable for me in ensuring consistency. On the Zend 1 project mentioned above, there are still some issues with poor, inconsistent database design that I haven't yet been able to get around to resolving. One of these is that different content types are stored in different tables with different field names, but we need to be able to make them work consistently when resolving whether a given item is in date, even though the fields have different names.
If we had to use the query builder or write SQL, we'd be stuck writing the same chunk of the query over and over each time we needed to get the in-date items of each type, and it would be all too easy to mess it up and use the wrong field name when doing a union of different content types. But if we define a local scope on each model called scopeIsInDate() with an implementation specific to that model, we can then easily reuse that and ensure consistency.
We also have a use case where, based on the value of one field, or whether the ID of the model is in a hard-coded list, it needs to be treated as a different object. By using a global scope, we can create two models that extend a common base, and apply one scope to one model, and another to the other model. That way, even though we have only one database table, we can effectively treat it as two separate ones when using the models. Yes, a better database structure would resolve that, but this is a big legacy application and there's already lots to do to clean it up, so we can't justify it any time soon.
Going from writing PHP to writing SQL and back is hard on the grey matter. It will slow you down because:
If instead you only have to think about PHP's rules while writing a query, the mental load is significantly lower and your editor or IDE can help you out a lot more.
Now, it has to be said, sometimes there are queries where it's easier to write it out initially in SQL using something like MySQL Workbench, but I'd still advocate taking the time to go back and translate those queries into Eloquent if possible, or to the query builder if that's more practical. I consider raw SQL in a PHP file to be technical debt because, in addition to the other points above:
As always, sometimes if you're in a rush you can justify adding technical debt on a temporary basis, but that should be the exception, not the rule, and has to be justified.
With the reasons I'd recommend using an ORM out the way, here are some of the gotchas you should be aware of when making a decision about using one:
Honestly, the overwhelming majority of performance issues developers have with ORM's boil down to this. Again with a quote from Martin Fowler:
I've often felt that much of the frustration with ORMs is about inflated expectations. Many people treat the relational database "like a crazy aunt who's shut up in an attic and whom nobody wants to talk about"
If a developer treats an ORM like a black box and just writes queries without thinking about the SQL it generates, it's no surprise whatsoever if the generated queries don't perform well. It's still running queries under the bonnet, it's just that some of it is implicit. For instance, take this (relatively simple) example of an Eloquent query:
Post::join('user', 'posts.user_id', '=', 'users.id')->get();
If you use something like Clockwork to profile this query, the end result will probably look something like this:
SELECT * FROM posts
INNER JOIN users ON posts.user_id = users.id
And, to be fair, there are a few potential issues with this query.
posts and users tables, then that could easily include fields that you don't explicitly needposts.user_id, the join could perform badlyHowever, these issues really aren't inherent to using an ORM, but are to do with it being used naively. Assuming we do want to paginate these results, and the only field on users that we need is the name, we could achieve what we want by rewriting this query as follows:
Post::join('user', 'posts.user_id', '=', 'users.id')->select('posts.*', 'users.name')->paginate(20);
Yes, cursor pagination is a thing and will perform better than offset-based pagination in most cases, but I'm deliberately keeping this example as simple as possible.
As for the third issue, that's easy enough - just ensure that you're setting an appropriate foreign key.
This is nearly the same issue as that above, but it's important enough to deserve being mentioned separately.
Using an ORM effectively requires knowledge of your relational database. To write efficient queries with it, you need the same knowledge that you do to write the underlying query in SQL, AND knowledge of the ORM itself. If you start using it without learning to use a relational database (or let a junior dev who hasn't learned SQL properly), or don't profile your queries, you're going to run into problems.
I've often heard people suggest that using an ORM means your SQL skills atrophy. Quite frankly, I find that utterly laughable. I make a point of avoiding writing raw SQL when I can use an ORM, and I still often find myself having to write raw SQL, particularly if I'm prototyping a complex query. It does make it unnecessary to write out simple queries in SQL, but I'm not going to benefit in the slightest at this point in my career by writing something like SELECT * FROM posts over and over if I can call Post::all() instead.
It has to be said, there is inevitably some overhead from instantiating an ORM model, which can be quite a complex class, compared to instantiating an array of data, and if you have to work with a response that contains a large number of rows, it may be better to return arrays than model instances.
Case in point, the Zend 1 project I maintain has a number of reports which the client downloads once a week. This includes a report of all the current users in the system, and although users who leave are cleaned out of the system automatically, there's typically around thirty thousand rows returned from this query. That's big enough that the time taken to instantiate a model instance for each row can become significant, and you don't need a model instance if all you're going to do is dump the data out to a CSV file, so the additional overhead of instantiating the ORM models may not be worth it. So in those circumstances, you're better off using the query builder and returning an array - it'll be quicker and use less memory.
Fortunately, it's easy to convert an Eloquent query to a query builder one by calling the getQuery() method. That way you can write your query using Eloquent as normal, then convert it to a query builder instance, and return the data as an array.
Just because there isn't a method for a particular SQL statement, or the methods it does have don't have the options you need, doesn't mean you need to write it the whole thing as a raw query. There's still the various raw methods:
selectRawwhereRaw/orWhereRawhavingRaw/orHavingRaworderByRawgroupByRawBy making appropriate use of these methods, you can write only those parts of the query that absolutely need to be raw, without losing the advantages of using an ORM. For instance, if you need to use CASE ... WHEN statement to return a true or false value for if an entry is in date, or use GROUP_CONCAT() to concatenate some names from a related field into one field, you can easily do so using something like ->selectRaw('CASE WHEN expiry_date < NOW() THEN 'true' ELSE 'false', GROUP_CONCAT(name)').
Some more advanced parts of SQL can be harder to write using an ORM. For instance, take this query:
WITH RECURSIVE children(id, name, parent_id, depth) AS
(SELECT teams.*,
0 AS depth
FROM `teams`
WHERE id = 1
UNION ALL SELECT teams.*,
children.depth + 1
FROM teams
INNER JOIN children ON children.parent_id = teams.id)
SELECT *
FROM children
The WITH RECURSIVE CTE is a relatively new feature in SQL and not every implementation supports it. In addition, it's only useful in certain, quite specific circumstances. As such, support for it is limited in most ORMs, and this is one use case where it might not be worth the bother of rewriting the query to use an ORM. However, it's not impossible. The Laravel CTE package extends Eloquent to add support for recursive queries, and even if you can't use that for some reason, it might be worth rewriting the inner query alone in Eloquent, then using toSql() to get the SQL from it and insert that into the outer query, something like this:
$teams = Team::where('id', 1)
->unionAll(Team::join('children', 'children.parent_id', '=', 'teams.id')
->selectRaw('teams.*, children.depth + 1')
->toSql();
$query = "WITH RECURSIVE children(id, name, parent_id, depth) AS ($teams) SELECT * FROM children";
It's not perfect, but this at least means some of the query is expressed using Eloquent, making it easier to maintain and debug.
Just because a query isn't written manually doesn't mean it's not inefficient, and sometimes there can be hidden queries you're not aware of. Third-party packages can be a source of this, and the authentication system can trigger some less-than-obvious queries which can be cached. For this reason, it's a really good idea to profile your pages to make sure they're performing as expected.
I favour Clockwork as my profiling tool of choice, but Laravel Telescope and Laravel Debugbar are also solid options for this.
One of the advantages I've heard claimed for ORMs in the past is being able to migrate from, say, MySQL to PostgreSQL without making any changes to the code base. Honestly, I don't think this one is very likely unless your queries are very simple. Any call to any of the *raw() would need to be manually checked and migrated, and I don't think any sizeable application would be able to get away without having any of these. It may be you can find a third-party package to add custom methods to support these features directly, or can write your own, but it may not be worth the bother for only a handful of uses of that feature.
It can be convenient to be able to use an in-memory SQLite database for running your tests locally, but it likely won't be practical if you depend on any database-specific functionality, or for all the tables in a large application. As such I only tend to do this when working on packages, where there's only a handful of tables to deal with.
Hopefully this article has helped dispel some of the appalling myths, misconceptions, and general confusion that seem to be widespread around using an ORM. If there's one thing I hope you take away from this article it's that the ORM isn't a black box, but a layer of abstraction over your relational database, and if you don't bear that in mind, it's no surprise if you go on to experience performance problems. When used properly, an ORM is an extremely useful tool that is applicable to nearly every query you're likely to write, and it will help you make your code more readable, maintainable, performant, type-safe and secure.
]]>However, by default it's a bit too open. A malicious user could request an image at an excessive size as part of a denial of service attack. For that reason, it's considered good practice to set a maximum image size, and sign all requests so that you can be sure they're authorized by your application. This works fine if your images are being requested somewhere you can sign them easily, such as in a Blade template. However, doing so in the context of a React or Vue application can potentially be much harder because they're working on the front end and so can't sign requests that are made dynamically in the same way, at least not without you exposing your application's key to the front end, which would be really risky. An API endpoint can return URLs for pre-signed specific versions of the image, but that's not as flexible as being able to adjust what you get back via query parameters on the fly.
I'm currently working on an application that uses GraphQL for the API, and for that I wanted to use Glide to enable responsive images and minimise the size of the payload. Having recently rewritten this blog in Gatsby, I'd had some exposure to the Sharp plugin, which allows you to query for an image at specific dimensions. It struck me that I could probably do something similar with GraphQL in the context of a Laravel application. Since the GraphQL queries that would return the image URLs and other data were being handled server side, they could in theory accept parameters for the required images, validate that the specified values were acceptable, and return a secure, signed URL for that image for consumption by the front end. Since the frontend was having to make an AJAX request to fetch the items to show anyway, it could request the URLs as part of the same AJAX request as the rest of the items on a page, then render the images along with the rest of the content. Here I'll demonstrate how to do this.
The first thing to do is implement a controller for returning images via Glide. This will differ between frameworks so you'd need to check the Glide documentation, but a typical Laravel version would look something like this:
<?php
namespace App\Http\Controllers;
use Illuminate\Contracts\Filesystem\Filesystem;
use Illuminate\Http\Request;
use League\Glide\Filesystem\FileNotFoundException;
use League\Glide\Responses\LaravelResponseFactory;
use League\Glide\ServerFactory;
use League\Glide\Signatures\SignatureException;
use League\Glide\Signatures\SignatureFactory;
use Symfony\Component\HttpFoundation\StreamedResponse;
final class GlideController extends Controller
{
/**
* Storage
*
* @var Filesystem
*/
private $filesystem;
public function __construct(Filesystem $filesystem)
{
$this->filesystem = $filesystem;
}
public function __invoke(Request $request, string $path): StreamedResponse
{
try {
SignatureFactory::create((string)env('APP_KEY'))->validateRequest("/images/" . $path, $request->all());
$server = ServerFactory::create([
'response' => new LaravelResponseFactory($request),
'source' => $this->filesystem->getDriver(),
'cache' => $this->filesystem->getDriver(),
'cache_path_prefix' => '.cache',
'base_url' => '',
'max_image_size' => 1000 * 1000,
]);
return $server->getImageResponse("images/" . $path, $request->all());
} catch (SignatureException) {
abort(403);
} catch (FileNotFoundException) {
abort(404);
}
}
}
Note that I'm using a single action controller here. I've found myself gravitating more and more towards these for certain use cases, and I'm not the only one. For me, the biggest benefit of these is probably more concise naming - if a controller does one thing and one thing only, and the class name adequately describes that, you end up naming it something generic, like call(). By making the controller a single callable, you don't have to make that decision since it's taken out of your hands (it must be __invoke()). I'm also a big fan of callable classes in general - they're essentially closures on steroids since you can still pass dependencies to the constructor.
The SignatureFactory line is what handles validating the signature. It's based on the app key, and checks that the path and all its parameters are correctly signed. If the signature isn't valid, it will throw an exception, thus protecting the endpoint from requests that weren't already approved. We also specify a cache location, and a maximum image size to help prevent mass-resize attacks.
You can then register this controller in the usual way:
Route::get('/images/{path}', GlideController::class)->where('path', '.*')->name('glide');
If the images aren't going to be accessible to users who aren't logged in, it makes sense to apply whatever authentication middleware you're using to this route as well.
Now, depending on which GraphQL package you're using, defining the schema may be different. In this case, I'm using Lighthouse and the schema definition for an Eloquent model with an image would look something like this:
enum ImageFormat {
jpg
pjpg
webp
}
type Image {
id: ID!
caption: String!
dynamicImage(
width: Int @rules(apply: ["numeric", "max:1000"])
height: Int @rules(apply: ["numeric", "max:1000"])
quality: Int @rules(apply: ["numeric", "max:100"])
format: ImageFormat
): String @method
}
Here we're specifying what parameters the dynamicImage() field accepts, as well as applying some of Laravel's validation rules to the field to ensure it remains within acceptable ranges. We also use an enum to specify the supported image formats - these are actually limited to the options Glide provdes, but by specifying this as an enum, GraphQL tooling like GraphiQL can provide autocompletion for this parameter for a better developer experience when constructing queries. Note that we also use the @method directive to tell Lighthouse that this field maps to a method, not a property. If the method name differs from the field name, you would also need to specify that method name, eg @method(name: "myMethod").
Now, assuming your image was stored on the filesystem and the appropriate model field was called image_path, the method to retrieve the image URL on the model would look something like this:
use Illuminate\Support\Facades\URL;
use League\Glide\Urls\UrlBuilderFactory;
// Define model class...
public function dynamicImage(int $width = null, int $height = null, int $quality = null, string $format = null): ?string
{
$builder = UrlBuilderFactory::create('/images/', (string)env('APP_KEY'));
return URL::to($builder->getUrl($this->image_path, [
'w' => $width,
'h' => $height,
'q' => $quality,
'fm' => $format,
]));
}
Note that the parameters on the model must be specified in the same order as they are defined in the GraphQL schema for them to be lined up correctly, and must have the same names. I've only added the most obviously useful parameters here, namely height, width, quality and format, but if you need them there's nothing stopping you from adding further parameters - just don't forget to update the GraphQL schema to include them too.
We can then write GraphQL queries to call dynamicImage() with whatever parameters we wish to pass through, and will get back an appropriate URL in response. For instance, consider this query:
query {
items {
data {
id
caption
dynamicImage(width: 400, height:400, quality: 100, format: webp)
}
}
}
Here we assume a query has been defined called items which returns all instances of the Item GraphQL type. This would return, for each instance of the Item model, the ID, caption and the URL for an image of 100% quality, 400x400 pixels, in WebP format. Please also note that none of these arguments to dynamicImage() are required - if you leave one out, Glide will use the default value.
By calling dynamicImage() separately with different aliases, we can even fetch multiple versions of the image. In this example, we fetch it at two different sizes:
query {
items {
data {
id
caption
large_image: dynamicImage(width: 400, height:400, quality: 100, format: webp)
small_image: dynamicImage(width: 200, height:200, quality: 100, format: webp)
}
}
}
Then, when rendering a component, you could use the <picture> and <source> elements to show different versions based on media queries, as in this example of a simple React component used to render individual instances of Item:
const Card = (item) => (
<picture>
<source media="{max-width: 768px}" srcSet={item.small_image} />
<source media="{min-width: 769px}" srcSet={item.large_image} />
<img src={item.small_image} alt={item.caption} />
</picture>
)
This enables us to serve responsive images that are appropriately sized for the current screen resolution. On mobile devices, which may not always have a connection as fast as a desktop or laptop, it also means we aren't wasting bandwidth downloading images which are larger than necessary.
Along similar lines, you could fetch both WebP and JPEG versions of an image:
query {
items {
data {
id
caption
jpeg_image: dynamicImage(width: 400, height: 400, quality: 100, format: jpeg)
webp_image: dynamicImage(width: 400, height: 400, quality: 100, format: webp)
}
}
}
Then, we can use the WebP version of the image if the web browser supports it, falling back to JPEG if it doesn't, by using the <picture> and <source> elements again in our React component:
const Card = (item) => (
<picture>
<source type="image/webp" srcSet={item.webp_image} />
<img src={item.jpeg_image} alt={item.caption} />
</picture>
)
By doing this we aren't forced to work with the lowest common denominator in terms of image formats. We can instead offer WebP to users whose browsers support it, without locking out users on older browsers.
This technique should be easy enough to apply to other PHP frameworks since Glide is fairly framework agnostic and there are GraphQL implementations for most frameworks. It should also be applicable in other languages - for example, while I'm not aware of a direct equivalent of Glide in Node.js, you could conceivably use Sharp as the basis of your own custom endpoint to serve up dynamic images based on query parameters, and then serve signed URLs for it via GraphQL.
Responsive images are something that's often overlooked when trying to build a modern web app. An approach like this makes it an awful lot easier to serve appropriately-sized images on demand, without locking front-end devs into specific known dimensions that might not fit their use case.
]]>