GraphQL Types and Scalars

# CHAPTER 6

GraphQL Types and Scalars #

1. Introduction #

2. Learning Objectives #

• Identify and use the 5 built-in GraphQL Scalar types.

• Understand the concept of Custom Scalars (like Date or JSON).

• Use Enumeration (Enum) types to enforce strict data values.

• Differentiate between Object types and Scalar types.

3. Beginner-Friendly Explanation #

If you ask for a User (Object), GraphQL says, "I can't just give you a 'User', you need to tell me *which pieces of paper* inside the User you want." You then ask for the name (String) and age (Int). Strings and Integers are Scalars. They are the actual data that gets sent over the internet.

4. Real-World Examples #

• E-commerce Product: A Product is an Object. Its price is a Float (Scalar). Its inStock status is a Boolean (Scalar). Its category might be restricted to only "ELECTRONICS", "CLOTHING", or "FOOD". That restriction is an Enum.

• Event Management: You have an Event Object. You want to store when the event happens. GraphQL doesn't have a default "Date" type. So, you create a *Custom Scalar* called DateTime to handle calendar dates properly.

5. Detailed Code Examples #

Schema SDL:

# Enum: A special scalar restricted to these exact values
enum AccountStatus {
  ACTIVE
  SUSPENDED
  BANNED
}

# Object Type utilizing various Scalars
type UserProfile {
  id: ID!               # Unique identifier
  username: String!     # Text
  age: Int              # Whole number
  accountBalance: Float # Decimal number
  isVerified: Boolean   # True or false
  status: AccountStatus # Enum
}

type Query {
  getProfile: UserProfile
}

6. Query Examples #

query {
  getProfile {
    id
    username
    accountBalance
    isVerified
    status
  }
}

7. Mutation Examples #

mutation {
  updateStatus(id: "101", newStatus: SUSPENDED) {
    id
    status
  }
}

*(Notice that SUSPENDED is not in quotes. It is an Enum, not a String!)*

8. Schema Examples (Custom Scalars) #

Defining Custom Scalars:

scalar DateTime
scalar EmailAddress

type Message {
  content: String!
  sentAt: DateTime!
  senderEmail: EmailAddress!
}

*Note: While you define scalar DateTime in the schema, you must write the PHP validation logic in your backend to ensure it is actually a valid date.*

9. Best Practices #

• Use Enums Instead of Strings: If a field only has a set list of allowed values (like roles: ADMIN, USER, GUEST), always use an Enum. It prevents typos and makes the API self-documenting.

• Use the ID type: Even though an ID might look like a String or an Integer in your database, always type it as ID in GraphQL. It tells the frontend developer, "This field is meant as a unique identifier, not for math or display."

• Leverage Community Scalars: Instead of writing complex validation logic for custom scalars (like validating an Email format), look for open-source GraphQL scalar libraries in PHP.

10. Common Mistakes #

• Confusing Int and Float: Trying to pass a decimal value (e.g., 10.50) to an Int field will crash the query. Always use Float for money or measurements.

• Putting Quotes Around Enums: In JSON/GraphQL queries, Enums are written without quotes (status: ACTIVE, not status: "ACTIVE").

11. Mini Exercises #

1. 1. List the 5 default scalar types in GraphQL.

1. 2. If you want to store a user's height in meters (e.g., 1.75), which scalar should you use?

1. 3. Look at this schema: type Item { weight: Int }. Can a client request 12.5 as the weight?

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain the difference between an Object type and a Scalar type.

• Q: Why would you define a Custom Scalar instead of just using a String?

• Q: What is an Enum, and when should you use one?

15. FAQs #

Q: Do Enums have to be uppercase? A: By convention, yes, but it is not strictly required by the language. It makes them easily distinguishable from standard strings.

16. Summary #

17. Next Chapter Recommendation #