diff --git a/guide/provider.md b/guide/provider.md new file mode 100644 index 00000000..2527d7d7 --- /dev/null +++ b/guide/provider.md @@ -0,0 +1,127 @@ +--- +currentMenu: guide-provider +--- + +# Provider + +The `Provider` protocol creates a simple and predictable way for adding functionality and third party packages to your Vapor project. + +## Adding a Provider + +Adding a provider to your application takes 2-3 steps. + +### Add Package + +All of Vapor's providers end with the `-provider` syntax. You can see a list of [available providers](https://github.com/vapor?utf8=✓&query=-provider) by searching on our GitHub. + +To add the provider to your package, add it as a dependency in your `Package.swift` file. + +```swift +let package = Package( + name: "MyApp", + dependencies: [ + .Package(url: "https://github.com/vapor/vapor.git", majorVersion: 0, minor: 16), + .Package(url: "https://github.com/vapor/mysql-provider.git", majorVersion: 0, minor: 4) + ] +) +``` + +> It's important to `vapor clean` or `vapor build --clean` after adding new packages. + +### Import + +Once the provider has been added, you can import it using `import VaporFoo` where `Foo` is the name of the provider. + +Here is what importing the MySQL provider looks like: + +```swift +import Vapor +import VaporMySQL + +let drop = Droplet(providers: [VaporMySQL.Provider.self]) + +// ... + +drop.serve() +``` + +Every provider comes with a class named `Provider`. Append the `Type` of this class to your `providers` array in the `Droplet`'s init method. + +### Config + +Some drivers may require a configuration file. For example, `VaporMySQL` requires a `Config/mysql.json` file like the following: + +```json +{ + "host": "localhost", + "user": "root", + "password": "", + "database": "vapor" +} +``` + +You will receive an error during the `Droplet`'s initialization if a configuration file is required. + +## Advanced + +You may choose to initialize the provider yourself. If you do, simply use the `initializedProvider` array instead. + +```swift +import Vapor +import VaporMySQL + +let mysql = VaporMySQL.Provider(host: "localhost", user: "root") + +let drop = Droplet(initializedProviders: [mysql]) + +... + +drop.serve() +``` + +## Create a Provider + +Creating a provider is easy, you just need to create a package with a class `Provider` that conforms to `Vapor.Provider`. + +### Example + +Here is what a provider for an example `Foo` package would look like. All the provider does is take a message, then print the message when the `Droplet` starts. + +```swift +import Vapor + +public final class Provider: Vapor.Provider { + public let message: String + public let provided: Providable + + public convenience init(config: Config) throws { + guard let message = config["foo", "message"].string else { + throw SomeError + } + + try self.init(message: message) + } + + public init(message: String) throws { + self.message = message + } + + public func afterInit(_ drop: Droplet) { + + } + + public func beforeServe(_ drop: Droplet) { + drop.console.info(message) + } +} +``` + +This provider wil require a `Config/foo.json` file that looks like: + +```json +{ + "message": "The message to output" +} +``` + +The provider can also be initialized manually with the `init(message: String)` init.