🌅 Docs Horizon

Automatically generate Frontend type definitions from your Laravel Backend structure. Bridge the gap between your Laravel models, validations, and migrations with TypeScript interfaces for seamless full-stack development.

✨ Features

• 🔍 Multi-Source Analysis - Extracts data from Models, Controller validations, and Migrations
• 🎯 TypeScript Generation - Creates clean TypeScript interfaces for your frontend
• 📄 JSON Schema Export - Generates JSON schema for API documentation
• 🚀 CLI Only - Secure generation through Artisan commands only
• 🔄 Smart Type Mapping - Intelligently converts PHP/Laravel types to TypeScript
• 📁 Organized Output - Creates structured files in resources/js/docs-api/

📦 Installation

composer require andrazero121/docs-horizon

The package will automatically register its service provider.

🚀 Usage

Generate Type Definitions

Run the Artisan command to analyze your Laravel application and generate type definitions:

php artisan docs:horizon

This command will:

1. 📊 Analyze all Models in app/Models/
2. 🔍 Extract validation rules from Controllers
3. 📋 Read column types from Migration files
4. 🔄 Merge and convert data to frontend-friendly format
5. 📝 Generate TypeScript and JSON files

Output Structure

After running the command, you'll find generated files in:

resources/js/docs-api/
├── types.ts        # TypeScript interface definitions
├── schema.json     # JSON schema for API documentation  
└── index.ts        # Barrel export file

📋 Example Output

Generated TypeScript Interfaces (types.ts)

// Auto-generated by Docs Horizon
// Do not edit this file manually

export interface Users {
  id: number;
  name: string;
  email: string;
  email_verified_at: string | null;
  password: string;
  remember_token: string | null;
  created_at: string;
  updated_at: string;
}

export interface Posts {
  id: number;
  title: string;
  content: string;
  excerpt: string | null;
  user_id: number;
  published: boolean;
  published_at: string | null;
  created_at: string;
  updated_at: string;
}

export interface Categories {
  id: number;
  name: string;
  slug: string;
  description: string | null;
  created_at: string;
  updated_at: string;
}

Generated JSON Schema (schema.json)

{
  "users": {
    "id": "number",
    "name": "string", 
    "email": "string",
    "email_verified_at": "string",
    "password": "string",
    "remember_token": "string",
    "created_at": "string",
    "updated_at": "string"
  },
  "posts": {
    "id": "number",
    "title": "string",
    "content": "string", 
    "excerpt": "string",
    "user_id": "number",
    "published": "boolean",
    "published_at": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

💡 Frontend Usage

In TypeScript/JavaScript

import { Users, Posts, Categories } from '@/docs-api';

// Type-safe object creation
const user: Users = {
  id: 1,
  name: 'John Doe',
  email: 'john@example.com',
  // TypeScript will ensure all required fields are present
};

// API response typing
async function fetchUser(id: number): Promise<Users> {
  const response = await fetch(`/api/users/${id}`);
  return response.json(); // Typed as Users interface
}

// Form validation
function validateUserForm(data: Partial<Users>): boolean {
  // Your validation logic with type safety
  return data.name !== undefined && data.email !== undefined;
}

In Vue.js

<script setup lang="ts">
import { ref } from 'vue';
import type { Users, Posts } from '@/docs-api';

const user = ref<Users>({
  id: 0,
  name: '',
  email: '',
  // All properties are typed and autocompleted
});

const posts = ref<Posts[]>([]);
</script>

In React

import React, { useState } from 'react';
import type { Users, Posts } from '@/docs-api';

export default function UserProfile() {
  const [user, setUser] = useState<Users | null>(null);
  const [posts, setPosts] = useState<Posts[]>([]);

  // Component logic with full type safety
}

🔧 How It Works

Docs Horizon uses a sophisticated multi-layer analysis approach:

1. Nova - Type Extraction Engine

• Scans Controller validation rules
• Parses Migration files for column definitions
• Maps Laravel validation types to TypeScript types

2. Rafflesia - Model Analysis

• Analyzes Eloquent Models
• Extracts fillable fields
• Determines table relationships

3. Lane - Data Conversion

• Merges data from all sources
• Resolves conflicts with smart prioritization
• Normalizes field names and types

4. Helvetica - File Generation

• Creates clean TypeScript interfaces
• Generates comprehensive JSON schemas
• Maintains consistent formatting

🎯 Type Mapping

Laravel/PHP Type	TypeScript Type	Notes
string	string	Text fields
integer, bigInteger	number	Numeric fields
boolean	boolean	True/false values
json	object	JSON objects
array	any[]	Array types
text, longText	string	Text content
timestamp, date	string	ISO date strings
decimal, float	number	Decimal numbers

🔄 Data Source Priority

When multiple sources define the same field, Docs Horizon uses this priority order:

1. Migration files (highest priority) - Most accurate column definitions
2. Model fillable fields - Business logic constraints
3. Controller validation rules (lowest priority) - Request validation

📚 Advanced Usage

Custom Type Mapping

You can extend the type mapping by modifying the generated files after creation, but remember they will be overwritten on the next generation.

Integration with Build Tools

Add the generation command to your build process:

{
  "scripts": {
    "build": "php artisan docs:horizon && npm run build",
    "dev": "php artisan docs:horizon && npm run dev"
  }
}

Watch Mode (Coming Soon)

php artisan docs:horizon --watch

🐛 Troubleshooting

Common Issues

No types generated?

• Ensure you have Models in app/Models/
• Check that your Models extend Illuminate\Database\Eloquent\Model
• Verify Migration files exist in database/migrations/

Missing fields in output?

• Check that fields are defined in $fillable array in your Models
• Ensure Migration files use standard Laravel column types
• Verify Controller validation rules use supported validation types

TypeScript errors?

• Make sure your TypeScript configuration includes the resources/js directory
• Update your path aliases to include @/docs-api

Debug Mode

Run with verbose output to see what's being processed:

php artisan docs:horizon -v

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Clone the repository
2. Install dependencies: composer install
3. Run tests: composer test
4. Check code style: composer cs-fix

📄 License

This package is licensed under the MIT License. See the LICENSE file for details.

🆘 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

🚀 Roadmap

• v1.1 - Relationship mapping support
• v1.2 - Watch mode for auto-regeneration
• v1.3 - Custom configuration file
• v1.4 - Support for Enum types
• v1.5 - GraphQL schema generation
• v2.0 - Plugin system for custom generators

🙏 Acknowledgments

• Inspired by the Laravel and TypeScript communities
• Built with love for full-stack developers
• Special thanks to all contributors and users

---

Made with ❤️ by andrazero121

⭐ Star this repo if it helped you! ⭐