README

A PHP library for building and working with the JSON Resume schema.

Introduction

Resume PHP is a library that provides a type-safe way to build and work with resumes following the JSON Resume schema. It offers a fluent builder interface, rigorous data validation, and automated serialization to schema-compliant JSON.

Requirements

• PHP 8.4 or higher
• Composer

Installation

You can install the package via composer:

composer require juststeveking/resume-php

Usage

Building a Résumé

The library uses strictly-typed Data Objects and Value Objects to ensure your data is always valid and compliant with the schema.

use JustSteveKing\Resume\Builders\ResumeBuilder;
use JustSteveKing\Resume\DataObjects\Basics;
use JustSteveKing\Resume\DataObjects\Location;
use JustSteveKing\Resume\DataObjects\Profile;
use JustSteveKing\Resume\Enums\Network;
use JustSteveKing\Resume\ValueObjects\Email;
use JustSteveKing\Resume\ValueObjects\Url;

// Create the basics section using Value Objects for Email and URL
$basics = new Basics(
    name: 'John Doe',
    label: 'Software Engineer',
    email: new Email('john@example.com'),
    url: new Url('https://johndoe.com'),
    summary: 'Experienced software engineer with 5+ years in web development.',
    location: new Location(
        address: '123 Main St',
        postalCode: '94105',
        city: 'San Francisco',
        countryCode: 'US',
        region: 'CA',
    ),
    profiles: [
        new Profile(Network::GitHub, 'johndoe', new Url('https://github.com/johndoe')),
        new Profile(Network::LinkedIn, 'johndoe', new Url('https://linkedin.com/in/johndoe')),
    ],
);

// Build the résumé fluently
$resume = (new ResumeBuilder())
    ->basics($basics)
    ->addWork(new \JustSteveKing\Resume\DataObjects\Work(
        name: 'Tech Corp',
        position: 'Senior Developer',
        startDate: '2020-01-01',
        summary: 'Led development of core platform features',
        highlights: ['Improved performance by 40%', 'Mentored junior developers'],
    ))
    ->build();

// Validate against the official JSON schema
$isValid = $resume->validate();

// Convert to schema-compliant JSON
$json = json_encode($resume, JSON_PRETTY_PRINT);

Hydrating from Existing Data

You can easily load an existing JSON or YAML résumé using the ResumeFactory.

use JustSteveKing\Resume\Factories\ResumeFactory;

// From a JSON string
$resume = ResumeFactory::fromJson($jsonString);

// From a YAML string
$resume = ResumeFactory::fromYaml($yamlString);

// From an associative array
$resume = ResumeFactory::fromArray($data);

Adding Education & Skills

use JustSteveKing\Resume\DataObjects\Education;
use JustSteveKing\Resume\DataObjects\Skill;
use JustSteveKing\Resume\Enums\EducationLevel;
use JustSteveKing\Resume\Enums\SkillLevel;

$resumeBuilder = (new ResumeBuilder())->basics($basics);

$resumeBuilder->addEducation(new Education(
    institution: 'University of Technology',
    area: 'Computer Science',
    studyType: EducationLevel::Bachelor,
    startDate: '2014-09-01',
    endDate: '2018-06-01',
));

$resumeBuilder->addSkill(new Skill(
    name: 'PHP',
    level: SkillLevel::Expert,
    keywords: ['Laravel', 'Symfony', 'API Development'],
));

$resume = $resumeBuilder->build();

Features

• Strictly Typed: Leverages PHP 8.4 features like property promotion and readonly classes for robust data integrity.
• Value Objects: Uses Email and Url value objects to enforce data quality at the point of creation.
• Fluent Builder: A developer-friendly interface for constructing complex resumes step-by-step.
• Schema Validation: Built-in validation using opis/json-schema against the official JSON Resume specification.
• Career Insights: Analyze your career data to calculate total experience, skill frequency, and identify work history gaps.
• Smart Serialization: Automatically filters out null or empty optional fields to keep your JSON output clean.
• CLI Tooling: A built-in command-line tool for validation and conversion.
• Internationalization (i18n): Support for localized labels in exports (e.g., English, Welsh).
• Exporters: Built-in support for transforming resumes to Markdown, YAML, and JSON-LD (Schema.org).

Exporting & Transformations

JSON-LD (Semantic Web)

The toJsonLd() method converts your résumé into a structured array following the schema.org/Person specification.

$jsonLd = $resume->toJsonLd();
echo json_encode($jsonLd, JSON_PRETTY_PRINT);

Markdown Export

Generate a clean, human-readable Markdown version of your resume.

// Basic export (defaults to English)
echo $resume->toMarkdown();

// Custom configuration and Localization
$markdown = $resume->toMarkdown(
    options: [
        'work' => true,
        'education' => true,
    ],
    locale: 'cy' // Welsh
);

Career Insights

The CareerAnalyzer service provides deep insights into your résumé data.

$insights = $resume->getInsights();

// Calculate total years of experience
echo $insights->getTotalYearsExperience(); // e.g., 8.5

// Identify gaps in work history (greater than 30 days)
$gaps = $insights->getWorkGaps();

// Get skill usage frequency based on mentions in work highlights
$skills = $insights->getSkillFrequency();

CLI Tooling

The library includes a resume binary for common tasks.

# Validate a résumé file
./vendor/bin/resume validate my-resume.json

# Export to different formats
./vendor/bin/resume export my-resume.yaml --format=markdown --locale=en
./vendor/bin/resume export my-resume.json --format=json-ld --output=profile.jsonld

Job Description Builder

Create structured job descriptions using the same fluent pattern.

use JustSteveKing\Resume\Builders\JobDescriptionBuilder;

$jobDescription = (new JobDescriptionBuilder())
    ->name('Senior PHP Developer')
    ->location('Remote')
    ->description('Lead our backend transition to PHP 8.4')
    ->addHighlight('Competitive salary')
    ->addSkill('PHP')
    ->addTool('Docker')
    ->addResponsibility('Code reviews')
    ->build();

Development

The project maintains high standards through automated tools:

• Testing: composer test (PHPUnit)
• Static Analysis: composer stan (PHPStan at Level 9)
• Code Style: composer pint (Laravel Pint)
• Refactoring: composer refactor (Rector)

License

The MIT License (MIT). Please see License File for more information.

Credits

• Steve McDougall
• All Contributors