Mike Mikina

Tutorial: Building a Facebook bot with Vapor 3 and Swift, part I

2019-06-25T20:01:32+02:00

Bots are everywhere! They are not taking over the world yet, but can definitely do a lot. Facebook has built a great ecosystem around Messenger. You can play with and use a lot of different Facebook bots, some of them are really useful, some of them are there just for fun 😉. Today I would like to show you how to build your own Messenger bot using Swift and Vapor framework. In part 1, I will start with a small simple bot that can just echo commands. In part 2, I will dive deep into the Facebook API and create a more interesting chat bot.

Let’s get started 🚀

Getting started with chatbots 🤖

You probably have seen bots on the Messenger platform. If not, go to the Messenger app on your smartphone and explore the Discover tab.

There are basically three different types of chatbots:

Simple notification chatbots - these can, for example, provide information about your package shipping.
Process flow chatbots - these can guide you through the process of, for example, ordering a pizza.
Conversational chatbots - these can help you resolve issues using NLP (Natural Language Processing).

In this tutorial I will focus on a simple notification chatbot, which will just echo all received messages.

How does the Facebook platform looks like?

To create a Messenger Bot first of all you need to create a Facebook app. This app has to be connected to a Facebook page.

Let’s start with the Facebook Page. It will be used as the identity of your Bot. You have to keep in mind that a Facebook bot is just an app which is handling messages for you. When people chat with a Bot they will see the Page name and the Page profile picture.

To create a new Facebook page, go to this address. Choose Business or brand and click Get started. Enter Page name and Category. For now you can skip the Add a profile picture and Add a cover photo steps.

Your Facebook page is ready. Now it’s time to create the Facebook app.

To create a new Facebook app you will need a Facebook Developer Account. It is very easy to get one and if you have ever done anything with the Facebook api chances are you already have one. You can create a new developer account on the Facebook for Developers website.

Now open the apps page and click the + Add a New App button.

Enter a Display Name and your Contact Email and click Create App ID. After creating an app you will be redirected to the app settings.

On the left sidebar, click the PRODUCTS + button, it will redirect you to the Add a Product page.

On this page click the Set Up button on the Messenger card. Messenger will be added to your app and you will be redirected to the settings page.

Inside the settings page look for the Access Tokens:

Select your Facebook page and then click the Edit Permissions button. Follow the creator, at the end you will see that your app has been linked: You've now linked Test to Facebook. Now you can access your Page Access Token. Copy it and save it; you will need it later.

Next look for the Webhooks section and click Setup Webhooks:

On this page you need to provide a Callback URL for your the messenger app. This url will be used to send information back to your Vapor app. Before you create it let me explain what exactly it is.

What is a Webhook

Webhook provides a mechanism for the Facebook platform to notify your application when a new event has occurred on the server. It is an easy way of communicating with the Facebook platform. Instead of constantly checking if there is a new message from the user, Facebook will call your app whenever a new message arrives or other event occurs.

Inside Vapor, a webhook is simply just a route which you can name as you want. For a Messenger bot you will have to create an endpoint with two types of HTTP methods: GET and POST.

Webhook with GET method: will only be used once for a request validation when you create a new page subscription during the webhook setup on the Facebook platform.
Webhook with POST method: this is the heart of your app. The Facebook platform will send all of the notifications here.

Before creating a webhook inside Vapor there is one more thing to consider. In order to test the Messenger bot on your Macbook you need to expose your machine to the outside connections. The simplest solution is to use tools like Ngrok or other similar apps that will create public URLs to your local web server. For more details how to setup and use Ngrok you can go here.

Just remember that default port for Vapor is 8080:

➜ ./ngrok http 8080

Setting Up Your Webhook

Now it’s time for the fun part, let’s create the Vapor app 🎉

Create a new Vapor project:

➜ vapor new Facebook-bot-with-Vapor-3

Set Swift 5.0 and Vapor 3.3.0 inside Package.swift, you can also clean up and remove FluentSQLite from your dependencies, as it won’t be needed. You can check what Package.swift should look like here.

Generate the Xcode project file and open it:

➜ vapor xcode -y

To verify the webhook, create a controller file with the verify function. To know what kind of data Facebook will send during the verification, check FB documentation.

Create the controller file: App/Controllers/BotController.swift

import Vapor

final class BotController {
  
  let FacebookVerifyToken = Environment.get("FBVERIFYTOKEN")

  func verify(_ req: Request) throws -> Future<String> {
    let mode = try req.query.get(String.self, at: "hub.mode")
    let token = try req.query.get(String.self, at: "hub.verify_token")
    let challenge = try req.query.get(String.self, at: "hub.challenge")
    
    if mode == "subscribe" && FacebookVerifyToken == token {
      return req.eventLoop.newSucceededFuture(result: challenge)
    }
    else {
      throw Abort(.forbidden)
    }
  }
}

From the request query you need to get three parameters: hub.mode, hub.verify_token and hub.challenge.

hub.mode is not described inside the documentation so I’m not sure if other options instead of subscribe are available. But to be sure just check if hub.mode is equal to subscribe.
hub.challenge is a random text sent by the Facebook platform which you have to return during webhook verification.
hub.verify_token is the token that you set during webhook setup. It’s a good idea to pass it as an environment variable instead of hardcoding it.

Remember to set FBVERIFYTOKEN as an environment variable inside the Xcode scheme:

or if you are running your app from the Terminal:

➜ FBVERIFYTOKEN=bot123 ./Run serve --hostname 127.0.0.1 --port 8080 --env development

The verify function will be used for request validation. Remember to add missing routes inside App/routes.swift:

import Vapor

public func routes(_ router: Router) throws {
  let botController = BotController()
  router.get("webhook", use: botController.verify)
}

Run the Vapor project and inside the Terminal execute this curl command:

➜ curl -X GET "localhost:8080/webhook?hub.verify_token=bot123&hub.challenge=CHALLENGE_ACCEPTED&hub.mode=subscribe"

CHALLENGE_ACCEPTED%

As a result of the curl inside the Terminal, you should see the following printed text: CHALLENGE_ACCEPTED.

Let’s also write a simple test for this function.

To simplify all of the tests, copy the Vapor ➡️ helper and paste it inside: Tests/AppTests/TestsHelper.swift file. Don’t forget to make the extension public so other tests can see it. Then create the test file Tests/AppTests/WebhookTests.swift and put the testWebhook function inside:

func testWebhook() throws {
  
  let expectation = self.expectation(description: "Webhook")
  var responseData: Response?
  var challenge: String?
  
  try app?.test(.GET, "/webhook?hub.mode=subscribe&hub.verify_token=test&hub.challenge=CHALLENGE_ACCEPTED") { response in
    responseData = response
    challenge = String(decoding: response.http.body.data!, as: UTF8.self)
    expectation.fulfill()
  }
  
  waitForExpectations(timeout: 5, handler: nil)
  
  XCTAssertEqual(responseData?.http.status, .ok)
  XCTAssertEqual(responseData?.http.contentType, MediaType.plainText)
  XCTAssertEqual(challenge, "CHALLENGE_ACCEPTED")
}

The Application.test function will create a request and call the webhook endpoint. The body will be assigned to the challenge variable. Don’t forget to create an expectation and fulfill it inside the closure. You can check the whole test file here: WebhookTests.swift. Set FBVERIFYTOKEN as an environment variable also for test scheme.

It’s time to connect your webhook with the Facebook platform. To do this go back to the Facebook page and look for Setup Webhooks inside the settings page.

Callback URL - put your Ngrok public url (or any other that you are using) here, don’t forget to add the /webhook route to the address.
Verify Token - here you need to enter verification token that will be sent back to the webhook. You can name it as you want, test, bot123 etc.
Subscription Fields - here you can select different types of webhook events that will be delivered to the webhook. For now just select messages and messaging_postbacks.

Confirm it by clicking Verify and Save. Don’t forget to run the Vapor app! After your webhook has been verified you can now move to message handling.

Receiving the messages

It’s time to create a function that will take care of the incoming messages via webhook POST.

To better understand what kind of structure will be there, check out the Facebook documentation: Webhook Events Reference. I have already created the file with a Facebook webhook response struct. Download it from Github and put it in Models/BotStructure.swift.

Inside BotController.swift add a function that will be responsible for receiving the messages from the Messenger platform:

func message(_ req: Request) throws -> Future<Response> {
  // #1
  let data = try req.content.decode(FBResponseWrapper.self)
  
  // #2
  let botService = try req.make(BotServiceProtocol.self)
  let messagesService = try req.make(MessagesServiceProtocol.self)
  
  return data.flatMap { result in
    // #3
    guard let messageInput = result.entry.last?.messaging.last else {
      // Beware that in some cases Facebook response may not contain any messages. 
      throw Abort(.badRequest)
    }

    // #4
    let fbMessage = try messagesService.createMessage(for: messageInput)
    return try botService.sendFBMessage(req, message: fbMessage, recipient: messageInput.sender)
  }
}

Let’s go through this code step by step:

#1: Content of the request will be decoded to the FBResponseWrapper struct. You can find this struct in the Models/BotStructure.swift file.
#2: Then create the bot service, which will be responsible for sending messages, and the messages service which will be responsible for handling the messages logic. Remember to use protocols, this way it will be easier to switch those dependencies inside tests. You can read more about it in my previous blog post: Using the dependency injection framework for testing in Vapor 3 and Swift.
#3: Get the incoming message. There can be more messages inside the request body, but for now just get the last one.
#4: Bot will echo all of the incoming messages back to the user. Using the messages service, create a response message and send it back to the user using the bot service.

Don’t forget to add all missing routes inside the App/routes.swift:

import Vapor

public func routes(_ router: Router) throws {
    let botController = BotController()
    router.get("webhook", use: botController.verify)
    router.post("webhook", use: botController.message)
}

Caveat:

As you may have noticed, the message function is not checking the source of the input, so anyone who knows the webhook address can send malicious requests and pretend to be a Messenger bot. There is a simple solution to this issue. Messenger is providing a signed signature of the body that you can access from header: X-Hub-Signature. An attacker would need your personal app secret to spoof the request. Read more in the documentation: Validating Webhook Events

I will write how to secure your webhook in part two of this tutorial.

Create a new message

The Facebook messenger platform offers additional settings for the initial conversation. This means that you can set a greeting message and a Get started button. Using the Get started button will help your bot initialize conversation and set a different first response. To set the Get started button you need to setup an additional payload for the get started action. To do this, simply send it to the Facebook API in a Terminal:

curl -X POST -H "Content-Type: application/json" -d '{
  "get_started": { "payload": "START" },
  "greeting":[{ "locale":"default", "text":"Hello 👋" }]
}' "https://graph.facebook.com/v2.6/me/messenger_profile?access_token=[PUT YOUR FB TOKEN HERE]"

You can read more about Get started button and Greeting Text in the Messenger documentation.

Now let’s create a messages service: Models/MessagesService.swift. Start with a protocol: MessagesServiceProtocol:

protocol MessagesServiceProtocol {
  func createMessage(for input: FBMessagingDetails) throws -> FBMessage
}

Then create a class that conforms to the MessagesServiceProtocol and the Service protocol:

class MessagesService: MessagesServiceProtocol, Service {
  func createMessage(for input: FBMessagingDetails) throws -> FBMessage {
    if input.postback?.payload == "START" {
      // #1
      return FBMessage(text: "Hi 👋 I'm Echo Bot, I will send back everything you write to me 😄")
    }
    else if let message = input.message {
      // #2
      return FBMessage(text: "Echo: \(message.text ?? "This format is not supported yet, sorry 😇")")
    }
    else {
      throw Abort(.badRequest)
    }
  }
}

createMessage function has a very simple logic:

#1: If there is a payload value and it matches with the predefined payload value it means that this is the initial conversation. The user has just clicked the Get Started button. In this case say hi to the user.
#2: If there is a message inside, create an echo message. Also remember to check if there is text inside the FBMessage struct. Text is optional, the user can send a sticker or any other type of message. In that case text will be nil.

To use the MessagesService don’t forget to register it as a MessagesServiceProtocol inside the app configuration file App/configure.swift:

services.register(MessagesServiceProtocol.self) { container in
  return MessagesService()
}

Sending the messages

You are almost there! The messages service is ready. Now let’s create the FBService which will handle the communication with the Messenger platform.

Create Models/BotService.swift and start with the protocol BotServiceProtocol:

protocol BotServiceProtocol {
  func sendFBMessage(_ req: Request, message: FBMessage, recipient: FBUserID) throws -> EventLoopFuture<Response>
}

The sendFBMessage function requires Request to get access to the Client object, which will allow you to send HTTP requests. Then create the class FBService that conforms to the BotServiceProtocol and the Service protocol:

class FBService: BotServiceProtocol, Service {
  let FacebookAPIToken = Environment.get("FBAPITOKEN")
  
  func sendFBMessage(_ req: Request, message: FBMessage, recipient: FBUserID) throws -> EventLoopFuture<Response> {
    // #1
    var fbMessagesAPI = URLComponents(string: "https://graph.facebook.com/v2.6/me/messages")!
    fbMessagesAPI.queryItems = [URLQueryItem(name: "access_token", value: FacebookAPIToken)]
    
    // #2
    return try req.client().post(fbMessagesAPI.url!, headers: HTTPHeaders.init([("Content-Type", "application/json")])) { body in
      try body.content.encode(json: FBSendMessage(message: message, recipient: recipient))
    }
  }
}

Sending the message to the Facebook platform is pretty straightforward:

#1: Prepare the API url, add access_token.
#2: Send POST request using the Client object. Inside the closure you can set the body of the request. All you have to do is to send a FBSendMessage struct with a message and a recipient.

To use the FBService don’t forget to register it as a BotServiceProtocol inside the app configuration file App/configure.swift:

services.register(BotServiceProtocol.self) { container in
  return FBService()
}

Now let’s create two additional tests to fully test the second webhook endpoint.

First of all, you need to create the FBService mock. You don’t want to send actual data to Facebook during testing. Create file Tests/AppTests/BotManagerMock.swift. Details of this file you can find here. Then modify setUp function to register BotServiceProtocol and MessagesServiceProtocol, inside the test file Tests/AppTests/WebhookTests.swift:

override func setUp() {
  super.setUp()
  self.fbServiceMock = FBServiceMock()
  
  app = try! Application.makeTest(configure: { (config, services) in
    services.register(BotServiceProtocol.self) { container in
      return self.fbServiceMock!
    }
    
    services.register(MessagesServiceProtocol.self) { container in
      return MessagesService()
    }
  }, routes: routes)
}

let testsURL: URL = {
  let directory = DirectoryConfig.detect()
  let workingDirectory = URL(fileURLWithPath: directory.workDir)
  return workingDirectory.appendingPathComponent("Tests", isDirectory: true)
}()

override func tearDown() {
  super.tearDown()
  
  app = nil
  fbServiceMock = nil
}

Now create a test for the initial message:

func testInitialMessage() throws {
  
  let expectation = self.expectation(description: "Webhook")
  var responseData: Response?
  // #1
  let jsonData = try Data(contentsOf: testsURL.appendingPathComponent("FB-request-1.json"))
  self.fbServiceMock!.response = HTTPResponse(status: .ok, body: "{}")
  // #2
  try app?.test(HTTPRequest(method: .POST, url: URL(string: "/webhook")!), beforeSend: { request in
    request.http.headers = HTTPHeaders.init([("Content-Type", "application/json")])
    // #3
    request.http.body = HTTPBody(data: jsonData)
  }, afterSend: { response in
    responseData = response
    expectation.fulfill()
  })
  
  waitForExpectations(timeout: 5, handler: nil)
  
  XCTAssertEqual(responseData?.http.status, .ok)
  // #4
  XCTAssertEqual(self.fbServiceMock?.responseMessage, "Hi 👋 I'm Echo Bot, I will send back everything you write to me 😄")
}

#1: Load the content of the FB-request-1.json file, you can get this file from here. This is the request which Facebook will send to your webhook after the user clicks the Get Started button.
#2: Application.test function will create a POST request to the webhook.
#3: Inside the beforeSend closure you can set the body of the request, simply assign the json data loaded earlier.
#4: Check if FBService mock has a proper message value.

You can check the whole test file here. It also has the second test for the echo message.

It’s time to play with your bot 😄. To find your Messenger Link, go to your fanpage: Settings > Messenger Platform and look for Your Messenger Link:

Don’t forget to run the Vapor project and set a proper webhook address. Copy your messenger link into Safari:

Summary ✅

As you can see, this Facebook bot is pretty simple. The goal of this post is to help you to understand the basics of the Messenger API and how to use it. You can check the repository with the entire project on Github.

On the next blog post I will show you more interesting functions that are available on the platform. I will also talk about how to secure the webhook and prevent it from being accessed by anyone who knows its address.

What do you think of the Messenger platform? Have you tried to create your own bot? Did you have any difficulties with the API? Let me know - along with your questions, comments or feedback - on Twitter @mikemikina.

Happy coding 😊

Using the dependency injection framework for testing in Vapor 3 and Swift

2019-04-10T20:12:12+02:00

In my previous blogpost, How to test controllers by mocking dependencies in Vapor 3 and Swift, I injected dependencies into the controller using a constructor, but it turns out that there is a better way to do it. Vapor 3 introduces a dependency injection framework, which allows you to register, configure, and create your application’s dependencies in a maintainable way.

Show me the code ☀️

Why should you use the dependency injection framework? 🤔

I was a little skeptical when I first read about it in the documentation. My main concern was that it would be hard to mock inside the tests. It turns out that it’s not.

The Service (vapor/service) framework provides you with a couple of interesting features:

Easy access to the collection of registered services
Configure preferences for certain services over others
Initialize one object and reuse it everywhere or create a new one for each call
Register different services depending on the environment

Creating a new service in your controller is very simple, just call .make(_:) on the request and pass the type you want.

let availabilityChecker = try request.make(AvailabilityCheckerProtocol.self)

You have to remember that the class that conforms to registered protocol has to conform to the Service protocol. You can achieve this by creating extension:

extension AvailabilityChecker: Service {}

The service protocol is just an empty protocol for declaring types that can be registered as a service.

How to use it inside the tests? 🛠

The key to this is using protocols instead of the concrete implementation.

If you create a service using the class that implements your protocol, for example, like this:

let availabilityChecker = try request.make(AvailabilityChecker.self)

Inside the tests it will be impossible to switch AvailabilityChecker for a mock object like AvailabilityCheckerMock.

So initializing the service as a protocol allows you to register different implementations for the application and for testing.

For the application, your configure.swift file will look like this:

services.register(AvailabilityCheckerProtocol.self) { container in
  return AvailabilityChecker()
}

For testing, when you will use Vapor ➡️ helper, you can simply register mock in the configure closure like this:

final class AvailabilityTests: XCTestCase {
  
  var app: Application?
  
  override func setUp() {
    super.setUp()
    app = try! Application.makeTest(configure: { (config, services) in
      services.register(AvailabilityCheckerProtocol.self) { container in
        return AvailabilityCheckerMock()
      }
    }, routes: testRoutes)
  }

Source code with those examples is available here: ⚙️Mocking-Dependencies-Vapor3.

Summary ✅

As you can see, when creating services it’s much better to use protocols over the concrete implementation. When using protocols it’s very easy to mock all of the dependencies inside tests.

It’s definitely worth playing around and experimenting with the service framework. If you haven’t yet you should give it a try 👍

What do you think? Did you have any issues with testing while using services? Let me know - along with your questions, comments or feedback - on Twitter @mikemikina

Happy coding 😊

How to test controllers by mocking dependencies in Vapor 3 and Swift

2019-03-19T20:11:05+01:00

Testing controllers with external dependencies, especially ones involving HTTP requests, is very tricky. That’s because sending actual requests would create a test that you could not rely on and is very slow. But there is a very simple technique that you are probably familiar with: using protocols and injecting dependencies into controllers. Recently I ran into an issue when I was trying to get parameters from routes inside unit tests. So today I would like to show you how easily you can also pass proper routes into testing functions in Vapor 3.

Let’s get started 🚀

Why do you even want to test controllers? 🤔

Imagine an online store. On the product details page users can check how many items are available. The thing is that availability system is an external service, so each time a user wants to check product status, an external service has to be called.

Because the external service may be down or items that users are looking for are no longer available, the controller has to return the proper information.

Mocking external dependencies ⚙️

You can’t check if an external service is working or not, but you can check if the controller is returning proper status codes by mocking the external service.

You’ve probably done this before, the idea is simple:

Use protocol for external dependency
Inject it inside controller, ex: inside init method
Inside test suite use mock object that conforms to the protocol

Let’s define simple protocol - AvailabilityCheckerProtocol:

protocol AvailabilityCheckerProtocol {
  func checkProduct(id: UUID, quantity: Int) throws -> ProductDetailsResponse
  var req: Request? { get set }
}

I have added var req: Request? to the protocol just because it’s easy to use client().get() method and get status from external service inside the implementation.

Now create a controller that will have checkAvailability function:

import Vapor
import Foundation

final class AvailabilityController {
  
  var availabilityChecker: AvailabilityCheckerProtocol
  
  init(availabilityChecker: AvailabilityCheckerProtocol) {
    self.availabilityChecker = availabilityChecker
  }
  
  func checkAvailability(_ req: Request) throws -> Future<Response> {
    let promise = req.eventLoop.newPromise(Response.self)
    availabilityChecker.req = req
    
    let productID = try req.parameters.next(UUID.self)
    let quantity = try req.parameters.next(Int.self)
    
    DispatchQueue.global().async {
      do {
        let productDetails = try self.availabilityChecker.checkProduct(id: productID, quantity: quantity)
        
        _ = productDetails.encode(status: (productDetails.quantity >= quantity ? .ok : .notFound), for: req).map {
          promise.succeed(result: $0)
        }
      }
      catch {
        promise.fail(error: error)
      }
    }
    
    return promise.futureResult
  }
}

Standard route for this will be routes.swift:

import Vapor

public func routes(_ router: Router) throws {
  let availabilityController = AvailabilityController(availabilityChecker: AvailabilityChecker())
  router.get("status", UUID.parameter, Int.parameter, use: availabilityController.checkAvailability)
}

If you would like, you can check the implementation of AvailabilityChecker() here. It is a simple class that conforms to AvailabilityCheckerProtocol protocol and gets data using req.client().get().

Writing the test 🛠

The trick is that when writing the test you have to initialize controller using Vapor app instance, otherwise the router will not be available. Since the parameters are taken from req.parameters, you need to inject a special test router into the Application instance.

To do this you can use some of the extensions that are used to test Vapor itself. You can find those ➡️ here. Don’t forget to make the extension public so other tests can see it.

Take a look at the makeTest(configure:routes:) function. This function is getting Router as an input parameter. Instead of providing routes(_ router: Router) from routes.swift file, all you need to do is to create your own routes with mocked dependencies and pass it just for testing.

Create XCTest file AvailabilityTests.swift:

import XCTest
@testable import Vapor
@testable import App

final class AvailabilityTests: XCTestCase {
  
  var app: Application?
  
  override func setUp() {
    super.setUp()
    
    app = try! Application.makeTest(routes: testRoutes)
  }
  
  override func tearDown() {
    super.tearDown()
    
    app = nil
  }
  
  private func testRoutes(_ router: Router) throws {
    let availabilityVC = AvailabilityController(availabilityChecker: AvailabilityCheckerMock())
    router.get("status", UUID.parameter, Int.parameter,
               use: availabilityVC.checkAvailability)
  }
}

As you can see AvailabilityController now has injected mock object AvailabilityCheckerMock(). It is simulating responses from server:

import XCTest
@testable import Vapor
@testable import App

class AvailabilityCheckerMock: AvailabilityCheckerProtocol {
  var req: Request?
  
  private let products = [
    ProductDetails(id: UUID(uuidString: "32AAEE05-C84C-4B6D-94F8-78648323807E")!, quantity: 10),
    ProductDetails(id: UUID(uuidString: "596CFCC7-63D8-4123-BF8B-2C598739DB53")!, quantity: 50)
  ]
  
  func checkProduct(id: UUID, quantity: Int) throws -> ProductDetailsResponse {
    guard let product = products.filter({$0.id == id}).first else {
      return ProductDetailsResponse(quantity: 0, status: .unavailable)
    }
    
    guard product.quantity >= quantity else {
      return ProductDetailsResponse(quantity: product.quantity, status: .unavailable)
    }
    
    return ProductDetailsResponse(quantity: product.quantity, status: .available)
  }
}

Now let’s say you would like to check if the controller is returning 404 code and status .unavailable when user asks for too many products with id 596CFCC7-63D8-4123-BF8B-2C598739DB53.

func testCheckProductAvailabilityNotEnough() throws {
  
  let expectation = self.expectation(description: "Availability")
  var responseData: Response?
  var productDetails: ProductDetailsResponse?
  
  try app?.test(.GET, "/status/596CFCC7-63D8-4123-BF8B-2C598739DB53/51") { response in
    responseData = response
    let decoder = JSONDecoder()
    productDetails = try decoder.decode(ProductDetailsResponse.self, from: response.http.body.data!)
    
    expectation.fulfill()
  }
  
  waitForExpectations(timeout: 5, handler: nil)
  
  XCTAssertEqual(responseData?.http.status, .notFound)
  XCTAssertEqual(responseData?.http.contentType, MediaType.json)
  XCTAssertEqual(productDetails?.quantity, 50)
  XCTAssertEqual(productDetails?.status, .unavailable)
}

⚠️ Don’t forget to use expectations and fulfill it inside the closure.

This test will try to reach the url: /status/596CFCC7-63D8-4123-BF8B-2C598739DB53/51. Still, AvailabilityController will respond to this call, but instead of AvailabilityChecker() the mocked version AvailabilityCheckerMock() will be used.

For more tests and the overall picture take a look at ➡️AvailabilityTests.swift file.

Summary ✅

Remember, you are not checking whether an external service is working, you are checking if controller is responding correctly. By providing the data from a different source, you can simply test the behavior of the controller. Think of this as switching the datasource in iOS 😊

Please keep in mind that this is a very simple example just to show how easily you can inject different routes in Vapor. In a normal situation you may consider moving logic from controllers to models and testing those models.

The whole sample app is available ➡️here.

What do you think? Have you been testing controllers in your projects? Do you have any tips or advice that you would like to share? Let me know - along with your questions, comments or feedback - on Twitter @mikemikina

Happy coding 😊

Watermarking photos with ImageMagick, Vapor 3 and Swift on macOS and Linux

2018-12-06T17:27:36+01:00

Back in the days (you remember web 2.0? 😉) I used to do a lot of programming around photos. Resizing, scaling, rotating and converting between formats. Recently, I had to create a web service that generates watermarked images using Vapor. It turns out that there are not very many libraries for image manipulation yet, so this simple task became an interesting problem to research.

There are two major image manipulation libraries: GD and ImageMagick. ImageMagick is a bit of an advanced library so I decided to go with this one first. There is an interesting Swift wrapper for ImageMagick called MagickWand. Unfortunately, it doesn’t support text manipulation at all so I had to dig deeper. I couldn’t find anything useful so I thought “why not to just use some ImageMagick C functions in Swift?” It turns out that this is quite easy to do!

If you are just interested in one particular topic, feel free to use links below:

Install ImageMagick
Wrapping ImageMagick into a Swift Package
How to use ImageMagick with Swift
Serving watermarked photos in Vapor
Summary

Install ImageMagick

In the develop section on ImageMagick website you can find documentation for MagickWand and MagickCore. Those are the interfaces written in C for interacting with ImageMagick processing libraries. Wrapping it in a Swift package is very easy, but first let’s install ImageMagick.

Let’s start with macOS. You can compile ImageMagick by yourself but for macOS it’s easier just to use Homebrew.

➜ brew install imagemagick@6

If you don’t specify @6 it will install the latest version by default. I had issues with version 7 on Linux so I decided to use older versions for both macOS and Linux.

After the installation you will notice that homebrew is not creating symlinks (more information about: keg-only dependencies). This part is important in order to get information that you need about ImageMagick:

For pkg-config to find imagemagick@6 you may need to set:
export PKG_CONFIG_PATH="/usr/local/opt/imagemagick@6/lib/pkgconfig"

You can just add PKG_CONFIG_PATH in terminal before each pkg-config command but it’s easier to add it permanently, if you are using zsh just run:

➜ echo 'export PKG_CONFIG_PATH="/usr/local/opt/imagemagick@6/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.zshrc

For Linux I’m using Ubuntu 18.04 with Swift 4.2. If you have pre installed ImageMagick it’s better to remove it before compiling:

➜ apt-get remove imagemagick && apt-get autoremove

You can get ImageMagick package here.

➜ wget https://www.imagemagick.org/download/ImageMagick-6.9.10-12.tar.gz
➜ tar xzvf ImageMagick-6.9.10-12.tar.gz
➜ cd ImageMagick-6.9.10-12

Inside ImageMagick source directory run:

➜ ./configure

When the configuration is finished, find the section called Delegate Library Configuration and check if JPEG and PNG support is there. If you see no on the third column you probably don’t have required dependencies like libpng12-dev and libjpeg-dev. You can easily install those using apt-get.

If the configuration is alright, just compile the source:

➜ make

and install:

➜ make install

To confirm that installation finished correctly just run:

➜ convert --version

If you see this error:

convert: error while loading shared libraries: libMagickCore-6.Q16.so.6: cannot open shared object file: No such file or directory

Just run:

➜ ldconfig /usr/local/lib/

ImageMagick has been installed. Now we can start with the fun part 😄

Wrapping ImageMagick into a Swift Package

To use ImageMagick inside Swift code you need to wrap it into a Swift system module package. By exposing header files your Swift code will be able to use all of ImageMagick functions.

Let’s begin by creating a new directory called SwiftImageMagick and initialize new Swift system module using Swift package manager:

➜ mkdir SwiftImageMagick
➜ cd SwiftImageMagick
➜ swift package init --type system-module

Open module.modulemap file. You should see code generated by SPM:

module SwiftImageMagick [system] {
  header "/usr/include/SwiftImageMagick.h"
  link "SwiftImageMagick"
  export *
}

Let’s start with macOS first. Change the name of the module to SwiftImageMagick > SwiftImageMagickMac.

Now, in order to tell how to compile and link all of the packages, you need to use pkg-config tool. You should already have it, if not just use brew to install it:

➜ brew install pkg-config

As I mentioned earlier you need to have PKG_CONFIG_PATH set so pkg-config can find ImageMagick.

➜ pkg-config --list-all | grep -i Magick

You should see a couple of packages:

➜  ~ pkg-config --list-all | grep -i Magick
Magick++              Magick++ - Magick++ - C++ API for ImageMagick (ABI Q16)
Wand-6.Q16            MagickWand - MagickCore - C API for ImageMagick (ABI Q16)
ImageMagick++         ImageMagick++ - Magick++ - C++ API for ImageMagick (ABI Q16)
MagickWand            MagickWand - MagickWand - C API for ImageMagick (ABI Q16)
ImageMagick           ImageMagick - ImageMagick - convert, edit, and compose images (ABI Q16)
MagickCore-6.Q16      MagickCore - MagickCore - C API for ImageMagick (ABI Q16)
Magick++-6.Q16        Magick++ - Magick++ - C++ API for ImageMagick (ABI Q16)
Wand                  MagickWand - MagickCore - C API for ImageMagick (ABI Q16)
MagickWand-6.Q16      MagickWand - MagickWand - C API for ImageMagick (ABI Q16)
ImageMagick++-6.Q16   ImageMagick++ - Magick++ - C++ API for ImageMagick (ABI Q16)
ImageMagick-6.Q16     ImageMagick - ImageMagick - convert, edit, and compose images (ABI Q16)
MagickCore            MagickCore - MagickCore - C API for ImageMagick (ABI Q16)

To find the header file path for ImageMagick:

➜  ~ pkg-config --cflags-only-I MagickWand       
-I/usr/local/Cellar/imagemagick@6/6.9.10-12/include/ImageMagick-6

In this directory /usr/local/Cellar/imagemagick@6/6.9.10-12/include/ImageMagick-6 you will find headers for MagickWand: wand/MagickWand.h

And the linker flags:

➜  ~ pkg-config --libs MagickWand
-L/usr/local/Cellar/imagemagick@6/6.9.10-12/lib -lMagickWand-6.Q16 -lMagickCore-6.Q16

Once again, open module.modulemap, add header and link:

module SwiftImageMagickMac [system] {
  header "/usr/local/Cellar/imagemagick@6/6.9.10-12/include/ImageMagick-6/wand/MagickWand.h"
  link "MagickWand-6.Q16"
  link "MagickCore-6.Q16"
  export *
}

Let’s do the same for Linux. You should also have pkg-config on your linux machine, if not just use:

➜ apt-get install pkg-config

Let’s check what pkg-config sees:

pkg-config --list-all | grep -i Magick

root@8cc05b6015fc:~# pkg-config --list-all | grep -i Magick
Wand-6.Q16            MagickWand - MagickCore - C API for ImageMagick (ABI Q16)
ImageMagick++-6.Q16   ImageMagick++ - Magick++ - C++ API for ImageMagick (ABI Q16)
MagickWand-6.Q16      MagickWand - MagickWand - C API for ImageMagick (ABI Q16)
ImageMagick           ImageMagick - ImageMagick - convert, edit, and compose images (ABI Q16)
Wand                  MagickWand - MagickCore - C API for ImageMagick (ABI Q16)
ImageMagick-6.Q16     ImageMagick - ImageMagick - convert, edit, and compose images (ABI Q16)
MagickCore            MagickCore - MagickCore - C API for ImageMagick (ABI Q16)
Magick++-6.Q16        Magick++ - Magick++ - C++ API for ImageMagick (ABI Q16)
MagickWand            MagickWand - MagickWand - C API for ImageMagick (ABI Q16)
ImageMagick++         ImageMagick++ - Magick++ - C++ API for ImageMagick (ABI Q16)
Magick++              Magick++ - Magick++ - C++ API for ImageMagick (ABI Q16)
MagickCore-6.Q16      MagickCore - MagickCore - C API for ImageMagick (ABI Q16)

Start with the headers:

root@8cc05b6015fc:~# pkg-config --cflags-only-I MagickWand
-I/usr/local/include/ImageMagick-6

And the linker flags:

root@8cc05b6015fc:~# pkg-config --libs MagickWand
-L/usr/local/lib -lMagickWand-6.Q16 -lMagickCore-6.Q16

To the module.modulemap below macOS part add linux module:

module SwiftImageMagickMac [system] {
  header "/usr/local/Cellar/imagemagick@6/6.9.10-12/include/ImageMagick-6/wand/MagickWand.h"
  link "MagickWand-6.Q16"
  link "MagickCore-6.Q16"
  export *
}

module SwiftImageMagickLinux [system] {
  header "/usr/local/include/ImageMagick-6/wand/MagickWand.h"
  link "MagickWand-6.Q16"
  link "MagickCore-6.Q16"
  export *
}

Remember to remove the dependencies section from Package.swift:

// swift-tools-version:4.2
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "SwiftImageMagick"
)

Now when everything is in place don’t forget to create a git repository and commit your changes.

➜ git init
➜ git add .
➜ git commit -m "Initial commit."

Now our package is ready. Let’s use it 😄

How to use ImageMagick with Swift

Now let’s create simple test app that will import the ImageMagick library and create 100x100px image filled with a red background, just to be sure that our package is working.

➜ mkdir MagicTest
➜ cd MagicTest
➜ swift package init --type executable

Creating executable package: MagicTest
Creating Package.swift
Creating README.md
Creating .gitignore
Creating Sources/
Creating Sources/MagicTest/main.swift
Creating Tests/
Creating Tests/LinuxMain.swift
Creating Tests/MagicTestTests/
Creating Tests/MagicTestTests/MagicTestTests.swift
Creating Tests/MagicTestTests/XCTestManifests.swift

SPM will create the basic structure for you; --type executable will tell SPM to create a command line tool.

First of all, you need to add SwiftImageMagick as a dependency to Package.swift. You can add it as path to your local git repository:

// swift-tools-version:4.2
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "MagicTest",
    dependencies: [
        .package(url: "../SwiftImageMagick", .branch("master")),
    ],
    targets: [
        .target(
            name: "MagicTest",
            dependencies: []),
        .testTarget(
            name: "MagicTestTests",
            dependencies: ["MagicTest"]),
    ]
)

Compile it to be sure that your dependency is reachable:

➜  MagicTest swift build
Fetching /Users/mike/Documents/projects/playground/SwiftImageMagick
Completed resolution in 0.35s
Cloning /Users/mike/Documents/projects/playground/SwiftImageMagick
Resolving /Users/mike/Documents/projects/playground/SwiftImageMagick at master
'SwiftImageMagick' /Users/mike/Documents/projects/playground/MagicTest/.build/checkouts/SwiftImageMagick-2878331876767139303: warning: system packages are deprecated; use system library targets instead
Compile Swift Module 'MagicTest' (1 sources)
Linking ./.build/x86_64-apple-macosx10.10/debug/MagicTest

If you are using Swift 4.2 you will also see the following: warning: system packages are deprecated; use system library targets instead - this is related to System Library Targets.

Then, inside main file of your app (./Sources/MagicTest/main.swift) remove everything and import ImageMagick library.

#if os(Linux)
import SwiftImageMagickLinux
#else
import SwiftImageMagickMac
#endif

You can tell if you program is running on Linux or on macOS by using Swift build configuration import test.

Now to compile the app you also need to provide the path to headers and linker, the same one that you got last time using pkg-config. It’s also a good idea to check if there are any other flags that you need to provide:

➜  MagicTest pkg-config --cflags-only-other ImageMagick
-DMAGICKCORE_HDRI_ENABLE=0 -DMAGICKCORE_QUANTUM_DEPTH=16

Let’s add them all up:

➜ swift build -Xswiftc -I/usr/local/Cellar/imagemagick@6/6.9.10-12/include/ImageMagick-6 -Xlinker -L/usr/local/Cellar/imagemagick@6/6.9.10-12/lib -Xlinker -lMagickWand-6.Q16 -Xlinker -lMagickCore-6.Q16 -Xcc -DMAGICKCORE_HDRI_ENABLE=0 -Xcc -DMAGICKCORE_QUANTUM_DEPTH=16
Fetching /Users/mike/Documents/projects/playground/SwiftImageMagick
Completed resolution in 0.35s
Cloning /Users/mike/Documents/projects/playground/SwiftImageMagick
Resolving /Users/mike/Documents/projects/playground/SwiftImageMagick at master
'SwiftImageMagick' /Users/mike/Documents/projects/playground/MagicTest/.build/checkouts/SwiftImageMagick--9014361064470696861: warning: system packages are deprecated; use system library targets instead
Compile Swift Module 'MagicTest' (1 sources)
Linking ./.build/x86_64-apple-macosx10.10/debug/MagicTest

Success! 😄 Library is working, now let’s create an Xcode project file and add some code.

➜ swift package generate-xcodeproj

Run ./MagicTest.xcodeproj using Xcode 10.

When you try to compile it using Xcode you will see the same error as you had in the terminal:

It’s actually very easy to fix. Just open Build settings and find Header search path and add the path:

Do the same for Library search path:

Don’t forget to add Other Swift Flags:

Hit Cmd + R and everything should compile and run without any warnings.

Of course, all of these changes will be gone when you would like to regenerate xcodeproj again in the future. You can use xcconfig to store them but be aware that there are some weird issues with Xcode 10 (bug reported on radar).

Create a new file: Package.xcconfig

LIBRARY_SEARCH_PATHS = /usr/local/Cellar/imagemagick@6/6.9.10-12/lib
HEADER_SEARCH_PATHS = /usr/local/Cellar/imagemagick@6/6.9.10-12/include/ImageMagick-6
OTHER_SWIFT_FLAGS = -Xcc -DMAGICKCORE_HDRI_ENABLE=0 -Xcc -DMAGICKCORE_QUANTUM_DEPTH=16

Then generate the xcode project file:

➜ swift package generate-xcodeproj --xcconfig-overrides Package.xcconfig

The project should now compile without any errors or warnings.

When you have a properly working xcode project, open once again: Sources/MagicTest/main.swift

Below ImageMagick import add this:

MagickWandGenesis()

let wand = NewMagickWand()
let pixel = NewPixelWand()

MagickWandGenesis initializes the MagickWand environment. You also need to terminate the environment after you finish work. NewMagickWand creates new wand resource that represents a structure which contains image. NewPixelWand creates new pixel wand which is responsible for color manipulation.

PixelSetColor(pixel, "red")
MagickSetBackgroundColor(wand, pixel)

PixelSetColor will set the color of the pixel wand. Use name - "red", hex value #FF0000 or rbg - rgb(255,0,0). You can even use “transparent” to make a transparent background if you save it as png.

Now, when color is applied to the wand, just create a new image and save it:

MagickNewImage(wand, 100, 100, pixel)
MagickWriteImage(wand, "test.jpg")

You can also provide the absolute path to the image, but if you don’t do so remember that the file will be created in Xcode DerivedData catalog.

It’s almost done: just release memory for the wand, pixel and terminate the environment:

DestroyMagickWand(wand)
DestroyPixelWand(pixel)
MagickWandTerminus()

Now run the application. I have uploaded the whole sample app to the GitHub.

If you didn’t provide the absolute path for the file, you can just open Products, select program name and click Show in Finder. You will find test.jpg there:

The test.jpg should looks like this:

So the ImageMagick is working fine. Let’s create new Vapor app and add watermark text 😄

At the beginning of this post I thought that I would create a helper library for image manipulation but this post is already too long so let’s just keep it simple and use ImageMagick commands inside Vapor. Library for image manipulation will be a good topic for the next post 😉

Serving watermarked photos in Vapor

This one will be pretty simple, just create a new Vapor project:

➜ vapor new WatermarkPhotos

By default, vapor new will create a project based on the api template. Right now, you need to add the ImageMagick wrapper dependency. It’s a good idea to update Swift version to 4.2 and Vapor to 3.1.0 if it’s still on 3.0.0 in your Package.swift file:

// swift-tools-version:4.2
import PackageDescription

let package = Package(
    name: "WatermarkPhotos",
    dependencies: [
        // 💧 A server-side Swift web framework.
        .package(url: "https://github.com/vapor/vapor.git", from: "3.1.0"),

        // 🔵 Swift ORM (queries, models, relations, etc) built on SQLite 3.
        .package(url: "https://github.com/vapor/fluent-sqlite.git", from: "3.0.0"),

        // 🎨 ImageMagick wrapper
        .package(url: "https://github.com/mikina/SwiftImageMagick", .branch("master"))
    ],
    targets: [
        .target(name: "App", dependencies: ["FluentSQLite", "Vapor"]),
        .target(name: "Run", dependencies: ["App"]),
        .testTarget(name: "AppTests", dependencies: ["App"])
    ]
)

Generate the Xcode project file and open it:

➜ cd WatermarkPhotos/
➜ vapor xcode -y

It may take a while as it has to fetch all of the dependencies.

At this point you have everything you need to get started. Let’s write a very simple test. It’s hard to compare image to image, as it would make your tests flaky, so let’s just check if watermark endpoint response is:

Returning status code 200 .ok
Content type is set to image/jpeg
Content length is greater than zero

Create a new test file: /Tests/AppTests/PhotoTests.swift

import XCTest
@testable import Vapor
@testable import App

final class PhotoTests: XCTestCase {

}

Unfortunately, Vapor 3.1 doesn’t have any helpers for tests yet, but you can use some of the extensions that are used to test Vapor itself. You can find those here.

Create a new tests helper: /Tests/AppTests/TestsHelper.swift and copy this private application extension. Don’t forget to make it public so other tests can see it. It should look like this.

Now go back to PhotoTests.swift and add this simple test:

import XCTest
@testable import Vapor
@testable import App

final class PhotoTests: XCTestCase {
  func testGetWatermakedPhoto() throws {
    let app = try Application.makeTest(routes: routes)

    try app.test(.GET, "/photos/show/barcelona") { response in
      XCTAssertEqual(response.http.status, .ok)
      XCTAssertEqual(response.http.contentType, MediaType.jpeg)
      let length = response.http.headers["content-length"].first!
      XCTAssertGreaterThan(Int(length)!, 0)
    }
  }

  static let allTests = [
    ("testGetWatermakedPhoto", testGetWatermakedPhoto)
  ]
}

Of course, this test will fail right now because there is no photo controller yet, so let’s go and create one.

Create file: /Sources/App/Controllers/PhotoController.swift

import Vapor
import Foundation

final class PhotoController {
  func show(_ req: Request) throws -> Response {
    return Response(using: req)
  }
}

Also, add the route for it in: /Sources/App/routes.swift

import Vapor

/// Register your application's routes here.
public func routes(_ router: Router) throws {
    // Photos controller
    let photoController = PhotoController()
    router.get("photos", "show", String.parameter, use: photoController.show)
}

If you are not familiar with routes, String.parameter means that you can pass a string value inside the route and it will be available as request parameters inside the controller.

Your photos url will looks like this:

http://localhost:8080/photos/show/barcelona

At this point it’s just responding with an empty page. Let’s go back to /Sources/App/Controllers/PhotoController.swift and add some code.

In a real life application you would keep a list of photos in a database and actual files inside external storage like S3 on AWS. But for this demo let’s keep it simple, just create new directory called photos inside the main project directory and add some photos there.

Inside PhotoController.swift add photos list:

private let photosList = ["barcelona.jpg", "oslo.jpg", "porto.jpg", "rome.jpg"]
private let photosDirectory = "photos"

You can get the photo name from request parameters:

let name = try req.parameters.next(String.self)
let filename = name.lowercased().appending(".jpg")

Just check if the file is on the list:

guard photosList.contains(filename) else {
  throw Abort(.notFound, reason: "Photo not found")
}

Before adding the watermark to the photo, let’s just load it from the disk and send it as a response.

In Vapor 3.1 there is a DirectoryConfig struct which can help you get the path to the working directory.

let directory = DirectoryConfig.detect()
let workingDirectory = URL(fileURLWithPath: directory.workDir)

Caveat:

When you will be running the app through Xcode there is one thing that you need to do. If you have checked DirectoryConfig you probably saw that there is a function for directory detection: detect(). There is a conditional compilation flag: #if Xcode

You need to define it in Active Compilation Conditions:

Or just add it to Package.xcconfig:

SWIFT_ACTIVE_COMPILATION_CONDITIONS[config=Debug] = Xcode

And generate the xcodeproject file:

➜ swift package generate-xcodeproj --xcconfig-overrides=Package.xcconfig

Of course it will not affect a linux build.

You are almost there. Now create Data with contents of the file and return it as jpeg response:

let data = try Data(contentsOf: workingDirectory.appendingPathComponent(photosDirectory, isDirectory: true).appendingPathComponent(filename))
return req.response(data, as: .jpeg)

PhotoController at this point will look like this:

func show(_ req: Request) throws -> Response {

  let name = try req.parameters.next(String.self)
  let filename = name.lowercased().appending(".jpg")

  guard photosList.contains(filename) else {
    throw Abort(.notFound, reason: "Photo not found")
  }

  let directory = DirectoryConfig.detect()
  let workingDirectory = URL(fileURLWithPath: directory.workDir)

  let data = try Data(contentsOf: workingDirectory.appendingPathComponent(photosDirectory, isDirectory: true).appendingPathComponent(filename))
  return req.response(data, as: .jpeg)
}

Run the application in Xcode and open the url:

http://localhost:8080/photos/show/barcelona

It’s time for the final step: adding the watermark.

Create the model file: /Sources/App/Models/Photo.swift

Import Vapor, Foundation and ImageMagick headers as you did in sample project:

#if os(Linux)
import SwiftImageMagickLinux
#else
import SwiftImageMagickMac
#endif

import Vapor
import Foundation

You will probably see an error like:

'magick/magick-config.h' file not found

This is the same error as you had in sample app. Just add Package.xcconfig and regenerate xcode project file:

swift package generate-xcodeproj --xcconfig-overrides=Package.xcconfig

Create class Photo with a file property:

final class Photo {
  private let file: URL

  init(file: URL) throws {

    guard FileManager.default.fileExists(atPath: file.path) else {
      throw Abort(.internalServerError, reason: "Photo file not found")
    }

    self.file = file
  }

It’s a good idea to check if the file exists, as error reporting from ImageMagick is not always the best.

Now create a function that will return the watermarked photo:

public func watermarked(with font: URL, and text: String) throws -> Data {

  guard FileManager.default.fileExists(atPath: font.path) else {
    throw Abort(.internalServerError, reason: "Font file not found")
  }

It takes the url to the font file that will be used and the watermark text as input.

Prepare magic stack:

MagickWandGenesis()

let wand = NewMagickWand()
let pixel = NewPixelWand()
let draw = NewDrawingWand()

I have already described those methods. What’s new here is the drawing wand: it will be used to draw on the image, or in this case to attach watermark text to the image.

Load the image into Magick Wand:

MagickReadImage(wand, file.path)

And prepare the drawing wand:

PixelSetColor(pixel, "white")
DrawSetFillColor(draw, pixel)
DrawSetFont(draw, font.path)
DrawSetFontSize(draw, 70)
DrawSetGravity(draw, CenterGravity)
DrawAnnotation(draw, 0, 0, text)

This is pretty straight forward; The pixel wand is being set to white color and attached to the drawing wand. Font, gravity parameter and size are also applied to the drawing wand. DrawAnnotation is attaching watermark text to the drawing wand.

What’s worth mentioning here is that you can set different gravity. Gravity is telling ImageMagick where it should put the drawing so you don’t have to calculate this. Using CenterGravity will draw the watermark text in the center of an image. Setting it to SouthWestGravity will draw the watermark in bottom left corner. There is no need to calculate the bounding box and positioning on the screen manually.

Draw the watermark text:

MagickDrawImage(wand, draw)

You also need to set the image format and compression quality before getting the data:

MagickSetImageCompressionQuality(wand, 85)
MagickSetImageFormat(wand, "jpg")

To get the data from ImageMagick just call MagickGetImageBlob:

var length = 0

guard let image = MagickGetImageBlob(wand, &length) else {
  throw Abort(.internalServerError, reason: "Can't get image from ImageMagick.")
}

MagickGetImageBlob will return UnsafeMutablePointer<UInt8> and all you have to do is create Data using bytes:

let data = Data(bytes: image, count: length)

Don’t forget to clean up and return the data:

DestroyMagickWand(wand)
DestroyPixelWand(pixel)
DestroyDrawingWand(draw)
MagickRelinquishMemory(image)
MagickWandTerminus()

return data

Your model is all good now. Let’s go back to the controller and use it.

Before using your model, you need to download the font that will be used for creating the watermark. You can get a lot of different fonts from the GoogleFont library. I’m using Open Sans. Just download the ttf file and put it inside the fonts directory inside your project.

In PhotoController.swift, add the property for the font directory and the property for the watermark text:

final class PhotoController {

private let photosList = ["barcelona.jpg", "oslo.jpg", "porto.jpg", "rome.jpg"]
private let photosDirectory = "photos"
private let fontsDirectory = "fonts"
private let watermarkText = "ImageMagick\nVapor"

Inside the show(_ req: Request) function, replace current photo loading with your Photo model:

let file = workingDirectory.appendingPathComponent(photosDirectory, isDirectory: true).appendingPathComponent(filename)
let font = workingDirectory.appendingPathComponent(fontsDirectory, isDirectory: true).appendingPathComponent("OpenSans-Regular.ttf")

let photo = try Photo(file: file)
let watermarkedPhoto = try photo.watermarked(with: font, and: watermarkText)

The whole PhotoController should look like this.

Now run the application in Xcode and open the url once again:

http://localhost:8080/photos/show/barcelona

Summary

When I recently tried to use ImageMagick in my Vapor project, I spent a couple of hours trying to figure out how to setup and wrap ImageMagick into a Swift package. I had a lot of issues with missing files and linker errors. After resolving all of those issues, using ImageMagick turns out to be very simple and straightforward 😄

Where do we go from here?

I strongly encourage you to play with ImageMagick. You can create a very handy and tailored library that you can re-use in your Vapor projects.

You should also try to run it on Linux if you haven’t tried it yet. I’m using Docker for development and I will be writing how to use it with Vapor in my next blog post.

How did you like it? Have you already tried using ImageMagick with Vapor? Did you run into any issues? Let me know - along with your questions, comments or feedback - on Twitter @mikemikina

Happy coding 😊

Today I started my blog. But why?

2018-04-09T22:17:26+02:00

In this blog I will be writing mostly about software development, Swift, iOS, machine learning, algorithms and other interesting topics that I have learned so far.

There cannot be a programmer’s blog without hello world! So here you go:

  let hello = "Hello World"

Of course in Swift using Playgrounds 😉

But why to start a new blog? Isn’t there enough blogs already? Couple of reasons 😉

I wanted to start this blog in 2016. Actually I wrote two posts back then but I never published them. Posts were almost finished, blog was also almost finished. I just had other more urgent projects that needed to be taken care of. At least that’s what I have told to myself.

So first lesson learned: finish what you have started. No matter what, just finish it. I’ve been following this pattern for a while now.

Second reason is much more important - learning while blogging. It’s a very different thing when you want to explain what you have just learnt to someone else. Suddenly you realize that you are not sure how things are actually working under the hood. In order to write a blog post about it, you need to dig deeper, read the documentation and gather more information. It’s all about learning.

Third reason - connecting with others. Blogging brings you closer to people. You will be surprised how other people would solve an issue that you are facing. Put yourself out there, let others see what you have to say.

Reason number four - give back to the community. I have been using open source libraries and learning from other blogs for ages. Now it’s time to contribute. Let the others learn from you. Exchange ideas, share the knowledge.

Last but not least - writing is hard. For engineers playing with code is a natural thing to do, playing with words is a hell of a different story. Good news is that every new blog post brings you closer to mastering this mysterious craft. You may know all of the technical stuff but communication is the key.

Long story short - I really encourage all of you to start blogging, if you are not a blogger yet 😉

Feel free to reach me on Twitter @mikemikina. I like discussing and talking about different ideas 😊