https://youtu.be/Ri0AtbiShIw

1. Service abstractions
Part 1: Queries
Matthias Noback
@matthiasnoback

2. Background story
● We create software for the PowerUsers company
● We sell electricity
● Once a month we send an invoice to our
customers

3. Invoicing
● Read the "smart" meter of our customers:
– "High" reading
– "Low" reading

5. Where do we get the meter reading from?

6. Meet the Enerjira API
● Request: GET /api/meter/{customerId}/
● Response:
{
"low": 13405
"high": 274200
}

7. Let's use Guzzle

9. Abstraction!
● Guzzle: has been problematic in the past
● Let's use HTTPlug

11. Nice
● Using an HTTP client abstraction is smart
● It is hopefully more stable than any concrete
HTTP client

12. Wrong level of abstraction
What if the source changes?
What if the protocol changes?

13. A recipe for a query abstraction
● The question defined as an interface with a
single query method
● The answer defined as a class (value object)

14. The question
What is the response to GET
/api/meter/{customerId}
"What are the meter readings for customer X?"

15. The question
interface MeterReadings
{
public function getForCustomer(CustomerId $customerId): Reading;
}

16. The answer
final class Reading
{
// ...
public function low(): int;
public function high(): int;
}

17. The implementation
final class EnerjiraMeterReadings implements MeterReadings
{
public function getForCustomer(CustomerId $customerId): Reading
{
// use the HTTP client here
}
}

19. Design feedback
● Use tests to get feedback on the design of your
code

20. Use case tests
Given customer "C" has a meter reading of 0 (low) and 100 (high)
And the high tariff for customer "C" is 0.05
When the system creates an invoice for customer "C"
Then the total amount on that invoice should be 5.00

21. use BehatBehatContextContext;
final class InvoicingContext implements Context
{
/**
* @When the system creates an invoice for customer :customerId
*/
public function createAnInvoice(string $customerId): void
{
// The step succeeds if it doesn't throw an exception
}
}

22. Don't use external systems
● Database
● Remote API
● File system
● System clock
● Random data

23. Testing
● If your dependency is an HTTP client, you'd have
to "mock" the response

25. Testing
● This ties your test to the specs of the Enerjira
API, even though that is really an
implementation detail.

26. Testing
● What if their API changes?
● What if we need to migrate to a different
service?

27. Testing
● If your dependency is a MeterReader, you can
create a simple stub (or fake).

29. The tests are better off with an
abstraction
● The high-level use case test doesn't have to deal
with low-level details

30. The tests are better off with an
abstraction
● Test doubles are easier to set up

31. The tests are better off with an
abstraction
● Application service and test code all speak
"domain language"

32. Advantages of using an abstraction for queries

33. It's your abstraction
Question and answer are defined in your domain
or application layer code

34. It's your abstraction
The implementation of the interface is
infrastructure code

35. It's your abstraction
Infrastructure code can be changed at any time:
– When we have to switch to Elektrickery, which uses
FTP
– Once we start installing our own smart meters

36. Question: do I need an abstraction?
When you reach outside your application,
introduce an abstraction.

37. Twitter: @matthiasnoback