Download the PHP package familysearch/fs-php-lite without Composer

FamilySearch PHP Lite SDK

⚠️ Security Notice: Access tokens are stored in plaintext by default. Enable encryption in production. See Security Considerations.

Lite PHP SDK for the FamilySearch API.

Warning: this SDK requires hard-coding the API endpoint URLs. That is considered bad practice when using the API. In most cases, FamilySearch does not consider URL changes as breaking changes. Read more about dealing with change.

There is a sample app in the /examples directory that demonstrates SDK usage.

Environments

The SDK supports three FamilySearch environments:

Integration

Internal testing environment for FamilySearch developers and CI/CD pipelines. Not intended for external developer use.

• Identity/OAuth: https://identint.familysearch.org
• Platform API: https://api-integ.familysearch.org
• Use case: Internal FamilySearch testing

Beta

Pre-production environment for testing upcoming API features and validating application compatibility before changes reach production.

• Identity/OAuth: https://identbeta.familysearch.org
• Platform API: https://apibeta.familysearch.org
• Use case: External developer pre-release testing

Production

Live production environment with real FamilySearch user data.

• Identity/OAuth: https://ident.familysearch.org
• Platform API: https://api.familysearch.org
• Use case: Live production data

Example:

Usage

Security Considerations

Session Token Encryption

⚠️ Important: By default, OAuth access tokens are stored in PHP $_SESSION in plaintext. This means tokens can be read by anyone with filesystem access to your server's session directory (typically /var/lib/php/sessions).

For production deployments, enable optional AES-256-GCM encryption to protect tokens at rest:

Generating an Encryption Key

Generate a secure 32-byte encryption key:

Key Storage Best Practices

✅ DO:

• Store encryption keys in environment variables
• Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault)
• Use different keys for different environments (dev, staging, production)
• Rotate keys periodically (every 90 days recommended)

❌ DO NOT:

• Hardcode keys in source code
• Commit keys to version control
• Reuse the same key across environments
• Use weak or predictable keys

Example with environment variable:

What Encryption Protects

Session token encryption protects against:

• ✅ Filesystem access - Attackers who gain read access to session files
• ✅ Backup exposure - Tokens remain protected in backups
• ✅ Disk forensics - Deleted session files cannot reveal plaintext tokens
• ✅ Accidental logging - Encrypted values logged instead of plaintext
• ✅ Shared hosting risks - Other tenants cannot read your tokens

What Encryption Does NOT Protect Against

Encryption is not a silver bullet. It does not protect against:

• ❌ Active server compromise - Attackers with code execution can access keys
• ❌ Memory dumps - Tokens are plaintext in memory during request processing
• ❌ XSS attacks - Client-side attacks bypass server-side encryption
• ❌ Session hijacking - Valid session IDs grant access regardless of encryption
• ❌ Network interception - HTTPS is required separately

Bottom Line: Encryption protects data at rest. You also need HTTPS, secure session management, XSS protection, and proper server hardening.

Enabling Encryption on Existing Deployments

Enabling encryption on an existing application is seamless and backward-compatible. No downtime or manual migration required.

Step 1: Generate Encryption Key

Step 2: Store in Environment Variable

Step 3: Update SDK Configuration

Step 4: Deploy Changes

Deploy your updated application. No manual intervention needed.

Step 5: Automatic Migration

The migration happens automatically:

1. Existing sessions with plaintext tokens continue to work (backward compatible)
2. New OAuth flows store tokens encrypted
3. When users re-authenticate, their tokens are encrypted automatically
4. After natural session expiration (~24 hours), all tokens are encrypted

No forced logout. No disruption. No manual migration scripts required.

Verification

Verify encryption is working:

Additional Security Recommendations

1. Enable HTTPS - Always use HTTPS in production
2. Secure session cookies - Set session.cookie_secure = 1 in php.ini
3. HTTPOnly cookies - Set session.cookie_httponly = 1 to prevent XSS
4. SameSite cookies - Set session.cookie_samesite = "Strict" for CSRF protection

5. Session directory permissions - Ensure session files are not world-readable:

6. Regular key rotation - Rotate encryption keys every 90 days

For comprehensive security guidance, see SECURITY.md which includes:

• Detailed threat model
• Server configuration best practices
• Key rotation procedures
• Production deployment checklist
• Incident response guidelines

Token Expiration Handling

The SDK provides comprehensive token expiration tracking and automatic re-authentication capabilities. FamilySearch access tokens expire based on two conditions (whichever comes first):

1. Absolute Expiration: 24 hours from token creation
2. Inactivity Expiration: 60 minutes since the last successful API call

The SDK tracks these conditions client-side and offers three flexible approaches to handle token expiration:

1. Proactive Expiration Checking

Check token expiration before making API requests:

2. Automatic Re-authentication Callback

Configure a callback to handle 401 responses automatically:

3. Enhanced Token Information

Retrieve detailed token metadata for custom handling:

Additional Features

• Activity Tracking: Each successful API call resets the 60-minute inactivity timer
• Automatic Request Replay: Failed requests are transparently retried after successful re-authentication
• Backward Compatible: Existing code continues to work without changes
• Configurable Thresholds: Customize warning thresholds and replay behavior

Complete Documentation

For detailed documentation including additional examples, configuration options, and request replay behavior, see TOKEN_EXPIRATION.md

Serialization with gedcomx-php

When the objects configuration option is set to true, the gedcomx-php library can be used for serialization from objects for requests and deserialization into objects for responses.

When a response body is present, it will be deserialized as either an Atom Feed or a FamilySearchPlatform object.

gedcomx-php must be installed and included separately. gedcomx-php version 3.1.2 or later is required.

Testing

The SDK includes comprehensive unit and integration tests with 77.47% code coverage.

Quick Start

Test Suite Statistics

• 202 tests with 486 assertions
• 77.47% line coverage (368/475 lines), 50.00% method coverage (15/30 methods)
• 133 unit tests (244 assertions) - Fast, no HTTP requests
• 69 integration tests (242 assertions) - Test against live FamilySearch integration API

Test Structure

Integration Test Credentials

Integration tests require FamilySearch integration environment credentials. Set these environment variables:

How to get credentials:

1. Visit https://developers.familysearch.org/
2. Create an account and register an application
3. Request integration environment access
4. Use your integration credentials for testing

Running Tests on Specific PHP Versions

Viewing Coverage Reports

See TESTING.md for detailed instructions to create testing for your own application.

Requirements

• PHP 7.4 or higher
• ext-curl
• ext-json
• Composer for dependency management

Development

Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Ensure all tests pass: composer test
5. Submit a pull request

CI/CD

Tests run automatically via GitHub Actions on:

• PHP 7.4, 8.0, 8.1, 8.2, 8.3, and 8.4
• Every push to master/main branches
• Every pull request
• Code coverage generated for PHP 8.3
• Coverage reports uploaded to Codecov

CI Status

• ✅ All PHP versions passing (7.4-8.4)
• ✅ 202 tests, 486 assertions
• ✅ 77.47% code coverage (368/475 lines)

See .github/workflows/tests.yml for CI configuration.

PHP Version Compatibility

Minimum: PHP 7.4
Tested: PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4
Recommended: PHP 8.2+ for security updates

All tests pass on PHP 7.4-8.4 with zero deprecation warnings.