Ferno allows you to easily connect your Vapor project with your Firebase realtime database. It is built with the brand new Vapor 3. It gives you a nice and clean interface to interact with the Firebase Realtime REST API. It will automatically turn the response into your class/struct!
Prerequisites
You will need:
- Vapor 3.0+
Installing
In your Package.swift file, add the line
.package(url: "https://github.com/vapor-community/ferno.git", from: "0.2.0")
Also make sure you add Ferno
as a dependency
dependencies: ["Vapor", ..., "Ferno"]
Setup
-
Ferno uses an access token to read and write to your database. First we will need to get your service account information.
- Log into the Firebase console
- Click the settings gear next to
Project Overview
- Select
Project settings
- Select the
SERVICE ACCOUNTS
tab - Click the button at the bottom that says
GENERATE NEW PRIVATE KEY
- This will download a
.json
file. You will now have access to the email and private key. You will pass those into the initialize during the next step.
-
Register
Ferno
as a Provider and importFerno
. This is usually done inconfigure.swift
import Ferno
let fernoConfig = FernoConfig(basePath: "database-url", email: "service-account-email", privateKey: "private-key")
services.register(fernoConfig)
try services.register(FernoProvider())
Parameters
There are some custom parameters to pass into functions. I want to go over all the parameters you will need to know.
[FernoQuery]
In GET requests, you might want to query on your data. This is what [FernoQuery]
is for.
FernoQuery
is an enum with:
case shallow(Bool)
case orderBy(FernoValue)
case limitToFirst(FernoValue)
case limitToLast(FernoValue)
case startAt(FernoValue)
case endAt(FernoValue)
case equalTo(FernoValue)
These are all the possible queries that are allowed on Firebase according to the docs
NOTES on [FernoQuery]
shallow(Bool)
cannot be mixed with any other query parameters.- you usually use
orderBy(FernoValue)
in conjunction with enums3-7
- using
orderBy(FernoValue)
alone will just order the data returned
FernoValue
You will notice most cases in FernoQuery
have a value of FernoValue
.
FernoValue
is just a wrapper for Bool, String, Int, Double, Float
. So you can just do .startAt(5)
and everything will work.
Examples of [FernoQuery]
Just using shallow:
[.shallow(true)]
Filter data to only return data that matches "age": 21
:
[.orderBy("age"), .equalTo(21)]
Just orderBy(returns data in ascending order):
[.orderBy("age")]
Usage
There are 6 functions that allow you to interact with your Firebase realtime database.
GET
There are two functions that allow you get your data.
client.ferno.retrieve(req: Request, queryItems: [FernoQuery], appendedPath: [String])
client.ferno.retrieveMany(req: Request, queryItems: [FernoQuery], appendedPath: [String])
The only difference between retrieve
and retrieveMany
is the return type.
retrieve
returns ->F
whereF
is of typeDecodable
retrieveMany
returns ->[String: F]
whereF
is of typeDecodable
andString
is the key
Example
- Define the value you want the data converted.
struct Developer: Content {
var name: String
var favLanguage: String
var age: Int
}
- Make the request. Make sure you set the type of the response so Ferno knows what to convert.
let developers: Future<[String: Developer]> = try client.ferno.retrieveMany(req: request, queryItems: [], appendedPath: ["developers"])
let developer: Future<Developer> = try client.ferno.retrieve(req: request, queryItems: [], appendedPath: ["developers", "dev1"])
POST
Used to create a new entry in your database
client.ferno.create(req: Request, appendedPath: [String], body: T) -> Future<FernoChild>
body: T
is of typeContent
.FernoChild
is a struct:
struct FernoChild: Content {
var name: String
}
FernoChild
is returned, because the API request returns the key from the newly created child.
Example
let newDeveloper = Developer(name: "Elon", favLanguage: "Python", age: 46) //conforms to Content
let newDeveloperKey: Future<FernoChild> = try client.ferno.create(req: request, appendedPath: ["developers"], body: newDeveloper)
DELETE
Used to delete an entry in your database
client.ferno.delete(req: Request, appendedPath: [String]) -> Future<Bool>
- the delete method will return a boolean depending on if the delete was successful
Example
let successfulDelete: Future<Bool> = try client.ferno.delete(req: request, appendedPath: ["developers", "dev-1"])
PATCH
update values at a specific location, but omitted values won't get removed
client.ferno.update(req: Request, appendedPath: [String], body: T -> Future<T>
- the update method will return the body
Example
struct UpdateDeveloperName: Content {
var name: String
}
let newDeveloperName = UpdateDeveloperName(name: "Kimbal") //conforms to Content
let updatedDeveloperName: Future<UpdateDeveloperName> = try client.ferno.update(req: request, appendedPath: ["developers", newDeveloperKey.name], body: newDeveloper) //newDeveloperKey.name comes from the create method
PUT
overwrite the current location with data you are passing in
client.ferno.overwrite(req: Request, appendedPath: [String], body: T -> Future<T>
Example
struct LeadDeveloper: Content {
var name: String
var company: String
var age: Int
}
let leadDeveloper = LeadDeveloper(name: "Ashley", company: "Bio-Fit", age: 20)
let leadDevResponse: Future<LeadDeveloper> = try client.ferno.overwrite(req: request, appendedPath: ["developers", newDeveloperKey.name], body: leadDeveloper)
Testing
Currently, tests were written using an actual dummy Firebase realtime database. If you want to run all of the tests, you will need to create a dummy Firebase realtime database.
Testing Setup
You need to go to Application+Testing.swift
and fill in the missing values based on your Firebase service account. Then you will be able to run tests.
Authors
- Austin Astorga - Main developer - My Github
License
This project is licensed under the MIT License - see the LICENSE.md file for details
Acknowledgments
- Vapor Discord (for helping me with all my issues <3)
- Stripe Provider as a great template! stripe-provider