Whoa! Look out!
Bonus chapter!
We know that our API is fully described using the Open API spec. Heck,
we can even see it by going to /api/docs.json.
This shows all our different endpoints and their fields.
It gets this delicious info by reading our code, PHPdoc, and other things.
And we know this is used to power the Swagger UI docs page.
Our API is also described by JSON-LD and Hydra.
And, both of these types of API docs can be used to power other things.
For example, search for "react admin", to find an open source React-based admin system.
This is super powerful and cool...
and it's been around for a long time.
And the way it works is...
amazing: we point it at our API documentation and then...
it just builds itself!
I think we should take it for a test drive.
Search for "api platform react admin" to find the API Platform docs page all about this.
This has some info...
but what we're really after is over here.
Click "Get Started".
This walks us through all the details, even including CORS config if you have that problem.
So... let's do this!
If you use the API Platform Docker distribution, this admin area comes pre-installed.
But it's also easy enough to add manually.
Right now, our app doesn't have any JavaScript, so we need to bootstrap everything.
Find your terminal and run: composer require encore This installs WebpackEncoreBundle...
and its recipe gives us a basic frontend setup.
When that's done, install the Node assets with: npm install Okay, flip back over to the docs.
API Platform has their own Node package that helps integrate with the admin.
So let's get that installed.
Copy the npm install line - you can also use yarn if you want -
paste it in the terminal, and add a -D at the end.
That -D isn't super important, but I tend to install my assets as devDependencies.
To get all of this working, ultimately,
we're going to render a single React component into a page.
To help with that, I'm going to install a UX package that's...
just really good at rendering React components.
It's optional, but nice.
Run: composer require symfony/ux-react Perfect.
Now, spin over and search for "symfony ux react" to find its documentation.
Copy this setup code: we need to add it to our app.js file...
over here in assets/.
Paste... and we don't need all of these comments.
I'll also move this code down below the imports.
Awesome! This basically says that it will look in an assets/react/controllers/ directory
and make every React component inside super easy to render in Twig.
So, let's create that: in assets/, add two new directories: react/controllers/.
And then create a new file called ReactAdmin.jsx.
For the contents, go back to the API Platform docs...
and it gives us almost exactly what we need.
Copy this...
and paste it inside our new file.
But first, it doesn't look like it, but thanks to the JSX syntax, we're using React,
so we need an import React from 'react'.
And... let's make sure we have that installed: npm install react -D Second,
take a look at the entrypoint prop.
This is so cool.
We pass the URL to our API homepage...
and then React admin takes care of the rest.
For us, this URL would be something like https://localhost:8000/api.
But... I'd rather not hardcode a "localhost" into my JavaScript.
Instead, we're going to pass this in as a prop.
To allow that, add a props argument...
then say props.entrypoint.
How do we pass this in?
We'll see that in just a minute.
All right, let's see if the system will even build.
Fire it up: npm run watch And...
syntax error!
It sees this .jsx syntax and...
has no idea what to do with it!
That's because we haven't enabled React inside of WebpackEncore yet.
Hit Ctrl+C to stop that...
then spin over and open webpack.config.js.
Find a comment that says .enableReactPreset().
There it is.
Uncomment that.
Now when we run npm run watch again...
it still won't work!
But it gives us the command we need to install the one missing package for React support!
Copy that, run it: And now when we try npm run watch ...
it works! Time to render that React component.
How do we do that?
This is the easy part.
In src/Controller/, create a new PHP class called AdminController.
This is probably going to be the most boring controller you'll ever create.
Make it extend AbstractController, and then add a public function called dashboard(),
which will return a Response, though that's optional.
Above this, add a Route() for /admin.
All we need inside is return $this->render() and then a template: admin/dashboard.html.twig.
Cool! Down in the templates/ directory, create that admin/ directory...
and inside, a new file called dashboard.html.twig.
Again, this is probably one of the most boring templates you'll ever make,
at least at the start.
Extend base.html.twig and add block body and endblock.
Now, how do we render the React component?
Thanks to that UX React package, it's super easy.
Create the element that it should render
into then add react_component() followed by the name of the component.
Since the file is called ReactAdmin.jsx
in the react/controllers/ directory, its name will be ReactAdmin.
And here's where we pass in those props.
Remember: we have one called entrypoint.
Oh, but let me fix my indentation...
and remember to add the </div>.
We don't need anything inside the div...
because that's where the React admin area will magically appear, like a rabbit out of a hat.
Pass the entrypoint prop set to the normal path() function.
Now, we just need to figure out the route name that API Platform uses for the API homepage.
This tab is running npm...
so I'll open a new terminal tab and run: php bin/console debug:router Woh!
Too big. That's better.
Scroll up a bit, and...
here it is.
We want: api_entrypoint.
Head back over, and pass that in.
Moment of truth!
Find your browser, change the address to /admin, and...
hello ReactAdmin!
Woh! Behind the scenes, that made a request to our API entrypoint,
saw all of the different API resources we have, and it created this admin!
I know, isn't that insane?
We won't go too deep into this, though you can customize it
and you almost definitely will need to customize it.
But we get a lot of stuff out of the box.
It's not perfect: it looks a little confused
by our embedded dragonTreasures, but it's already very powerful.
Even the validation works!
Watch: when I submit, it reads the server-side validation returned by our API
and assigned each error to the correct field.
And treasures is aware of our filters.
It's all here!
If this is interesting to you, definitely check it out further.
All right, team!
You did it!
You got through the first API Platform tutorial, which is fundamental to everything.
You now understand how resources are serialized, how resources relate to other resources, IRIs,
etc. All of these things are going to empower you no matter what API you're building.
In the next tutorial, we'll talk about users, security, custom validation,
user-specific fields and other wild stuff.
Let us know what you're building and, if you have any questions,
we're here for you down in the comments section.
Alright, friends!
Seeya next time!