
engineering-other-languages
PHP/Laravel, Ruby/Rails, Perl, .NET/C#/F#, and other languages and frameworks
- version
- 1.0.0
- GitHub stars
- 5
Install
/plugin install engineering-other-languages@skills-stackRun it inside Claude Code after adding the marketplace with /plugin marketplace add marslanalvi/SkillsStack.
Contents
Discovered from sourceSkills 25
Bash Defensive Patterns
Comprehensive guidance for writing production-ready Bash scripts using defensive programming techniques, error handling, and safety best practices to prevent common pitfalls and ensure reliability.
When to Use This Skill
- Writing production automation scripts
- Building CI/CD pipeline scripts
- Creating system administration utilities
- Developing error-resilient deployment automation
- Writing scripts that must handle edge cases safely
- Building maintainable shell script libraries
- Implementing comprehensive logging and monitoring
- Creating scripts that must work across different platforms
Detailed patterns and worked examples
Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.
Best Practices Summary
- Always use strict mode -
set -Eeuo pipefail - Quote all variables -
"$variable"prevents word splitting - Use [[]] conditionals - More robust than [ ]
- Implement error trapping - Catch and handle errors gracefully
- Validate all inputs - Check file existence, permissions, formats
- Use functions for reusability - Prefix with meaningful names
- Implement structured logging - Include timestamps and levels
- Support dry-run mode - Allow users to preview changes
- Handle temporary files safely - Use mktemp, cleanup with trap
- Design for idempotency - Scripts should be safe to rerun
- Document requirements - List dependencies and minimum versions
- Test error paths - Ensure error handling works correctly
- Use
command -v- Safer thanwhichfor checking executables - Prefer printf over echo - More predictable across systems
Bats Testing Patterns
Comprehensive guidance for writing comprehensive unit tests for shell scripts using Bats (Bash Automated Testing System), including test patterns, fixtures, and best practices for production-grade shell testing.
When to Use This Skill
- Writing unit tests for shell scripts
- Implementing test-driven development (TDD) for scripts
- Setting up automated testing in CI/CD pipelines
- Testing edge cases and error conditions
- Validating behavior across different shell environments
- Building maintainable test suites for scripts
- Creating fixtures for complex test scenarios
- Testing multiple shell dialects (bash, sh, dash)
Detailed patterns and worked examples
Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.
Testing Error Conditions
#!/usr/bin/env bats
@test "Function fails with missing file" {
run my_function "/nonexistent/file.txt"
[ "$status" -ne 0 ]
[[ "$output" == *"not found"* ]]
}
@test "Function fails with invalid input" {
run my_function ""
[ "$status" -ne 0 ]
}
@test "Function fails with permission denied" {
touch "$TMPDIR/readonly.txt"
chmod 000 "$TMPDIR/readonly.txt"
run my_function "$TMPDIR/readonly.txt"
[ "$status" -ne 0 ]
chmod 644 "$TMPDIR/readonly.txt" # Cleanup
}
@test "Function provides helpful error message" {
run my_function --invalid-option
[ "$status" -ne 0 ]
[[ "$output" == *"Usage:"* ]]
}
Testing with Dependencies
#!/usr/bin/env bats
setup() {
# Check for required tools
if ! command -v jq &>/dev/null; then
skip "jq is not installed"
fi
export SCRIPT="${BATS_TEST_DIRNAME}/../bin/script.sh"
}
@test "JSON parsing works" {
skip_if ! command -v jq &>/dev/null
run my_json_parser '{"key": "value"}'
[ "$status" -eq 0 ]
}
Testing Shell Compatibility
#!/usr/bin/env bats
@test "Script works in bash" {
bash "${BATS_TEST_DIRNAME}/../bin/script.sh" arg1
}
@test "Script works in sh (POSIX)" {
sh "${BATS_TEST_DIRNAME}/../bin/script.sh" arg1
}
@test "Script works in dash" {
if command -v dash &>/dev/null; then
dash "${BATS_TEST_DIRNAME}/../bin/script.sh" arg1
else
skip "dash not installed"
fi
}
Parallel Execution
#!/usr/bin/env bats
@test "Multiple independent operations" {
run bash -c 'for i in {1..10}; do
my_operation "$i" &
done
wait'
[ "$status" -eq 0 ]
}
@test "Concurrent file operations" {
for i in {1..5}; do
my_function "$TMPDIR/file$i" &
done
wait
[ -f "$TMPDIR/file1" ]
[ -f "$TMPDIR/file5" ]
}
Test Helper Pattern
test_helper.sh
#!/usr/bin/env bash
# Source script under test
export SCRIPT_DIR="${BATS_TEST_DIRNAME%/*}/bin"
# Common test utilities
assert_file_exists() {
if [ ! -f "$1" ]; then
echo "Expected file to exist: $1"
return 1
fi
}
assert_file_equals() {
local file="$1"
local expected="$2"
if [ ! -f "$file" ]; then
echo "File does not exist: $file"
return 1
fi
local actual=$(cat "$file")
if [ "$actual" != "$expected" ]; then
echo "File contents do not match"
echo "Expected: $expected"
echo "Actual: $actual"
return 1
fi
}
# Create temporary test directory
setup_test_dir() {
export TEST_DIR=$(mktemp -d)
}
cleanup_test_dir() {
rm -rf "$TEST_DIR"
}
Integration with CI/CD
GitHub Actions Workflow
name: Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Bats
run: |
npm install --global bats
- name: Run Tests
run: |
bats tests/*.bats
- name: Run Tests with Tap Reporter
run: |
bats tests/*.bats --tap | tee test_output.tap
Makefile Integration
.PHONY: test test-verbose test-tap
test:
bats tests/*.bats
test-verbose:
bats tests/*.bats --verbose
test-tap:
bats tests/*.bats --tap
test-parallel:
bats tests/*.bats --parallel 4
coverage: test
# Optional: Generate coverage reports
Best Practices
- Test one thing per test - Single responsibility principle
- Use descriptive test names - Clearly states what is being tested
- Clean up after tests - Always remove temporary files in teardown
- Test both success and failure paths - Don't just test happy path
- Mock external dependencies - Isolate unit under test
- Use fixtures for complex data - Makes tests more readable
- Run tests in CI/CD - Catch regressions early
- Test across shell dialects - Ensure portability
- Keep tests fast - Run in parallel when possible
- Document complex test setup - Explain unusual patterns
C# Testing Patterns
Comprehensive testing patterns for .NET applications using xUnit, FluentAssertions, and modern testing practices.
When to Activate
- Writing new tests for C# code
- Reviewing test quality and coverage
- Setting up test infrastructure for .NET projects
- Debugging flaky or slow tests
Test Framework Stack
| Tool | Purpose |
|---|---|
| xUnit | Test framework (preferred for .NET) |
| FluentAssertions | Readable assertion syntax |
| NSubstitute or Moq | Mocking dependencies |
| Testcontainers | Real infrastructure in integration tests |
| WebApplicationFactory | ASP.NET Core integration tests |
| Bogus | Realistic test data generation |
Unit Test Structure
Arrange-Act-Assert
public sealed class OrderServiceTests
{
private readonly IOrderRepository _repository = Substitute.For<IOrderRepository>();
private readonly ILogger<OrderService> _logger = Substitute.For<ILogger<OrderService>>();
private readonly OrderService _sut;
public OrderServiceTests()
{
_sut = new OrderService(_repository, _logger);
}
[Fact]
public async Task PlaceOrderAsync_ReturnsSuccess_WhenRequestIsValid()
{
// Arrange
var request = new CreateOrderRequest
{
CustomerId = "cust-123",
Items = [new OrderItem("SKU-001", 2, 29.99m)]
};
// Act
var result = await _sut.PlaceOrderAsync(request, CancellationToken.None);
// Assert
result.IsSuccess.Should().BeTrue();
result.Value.Should().NotBeNull();
result.Value!.CustomerId.Should().Be("cust-123");
}
[Fact]
public async Task PlaceOrderAsync_ReturnsFailure_WhenNoItems()
{
// Arrange
var request = new CreateOrderRequest
{
CustomerId = "cust-123",
Items = []
};
// Act
var result = await _sut.PlaceOrderAsync(request, CancellationToken.None);
// Assert
result.IsSuccess.Should().BeFalse();
result.Error.Should().Contain("at least one item");
}
}
Parameterized Tests with Theory
[Theory]
[InlineData("", false)]
[InlineData("a", false)]
[InlineData("ab@c.d", false)]
[InlineData("user@example.com", true)]
[InlineData("user+tag@example.co.uk", true)]
public void IsValidEmail_ReturnsExpected(string email, bool expected)
{
EmailValidator.IsValid(email).Should().Be(expected);
}
[Theory]
[MemberData(nameof(InvalidOrderCases))]
public async Task PlaceOrderAsync_RejectsInvalidOrders(CreateOrderRequest request, string expectedError)
{
var result = await _sut.PlaceOrderAsync(request, CancellationToken.None);
result.IsSuccess.Should().BeFalse();
result.Error.Should().Contain(expectedError);
}
public static TheoryData<CreateOrderRequest, string> InvalidOrderCases => new()
{
{ new() { CustomerId = "", Items = [ValidItem()] }, "CustomerId" },
{ new() { CustomerId = "c1", Items = [] }, "at least one item" },
{ new() { CustomerId = "c1", Items = [new("", 1, 10m)] }, "SKU" },
};
Mocking with NSubstitute
[Fact]
public async Task GetOrderAsync_ReturnsNull_WhenNotFound()
{
// Arrange
var orderId = Guid.NewGuid();
_repository.FindByIdAsync(orderId, Arg.Any<CancellationToken>())
.Returns((Order?)null);
// Act
var result = await _sut.GetOrderAsync(orderId, CancellationToken.None);
// Assert
result.Should().BeNull();
}
[Fact]
public async Task PlaceOrderAsync_PersistsOrder()
{
// Arrange
var request = ValidOrderRequest();
// Act
await _sut.PlaceOrderAsync(request, CancellationToken.None);
// Assert — verify the repository was called
await _repository.Received(1).AddAsync(
Arg.Is<Order>(o => o.CustomerId == request.CustomerId),
Arg.Any<CancellationToken>());
}
ASP.NET Core Integration Tests
WebApplicationFactory Setup
public sealed class OrderApiTests : IClassFixture<WebApplicationFactory<Program>>
{
private readonly HttpClient _client;
public OrderApiTests(WebApplicationFactory<Program> factory)
{
_client = factory.WithWebHostBuilder(builder =>
{
builder.ConfigureServices(services =>
{
// Replace real DB with in-memory for tests
services.RemoveAll<DbContextOptions<AppDbContext>>();
services.AddDbContext<AppDbContext>(options =>
options.UseInMemoryDatabase("TestDb"));
});
}).CreateClient();
}
[Fact]
public async Task GetOrder_Returns404_WhenNotFound()
{
var response = await _client.GetAsync($"/api/orders/{Guid.NewGuid()}");
response.StatusCode.Should().Be(HttpStatusCode.NotFound);
}
[Fact]
public async Task CreateOrder_Returns201_WithValidRequest()
{
var request = new CreateOrderRequest
{
CustomerId = "cust-1",
Items = [new("SKU-001", 1, 19.99m)]
};
var response = await _client.PostAsJsonAsync("/api/orders", request);
response.StatusCode.Should().Be(HttpStatusCode.Created);
response.Headers.Location.Should().NotBeNull();
}
}
Testing with Testcontainers
public sealed class PostgresOrderRepositoryTests : IAsyncLifetime
{
private readonly PostgreSqlContainer _postgres = new PostgreSqlBuilder()
.WithImage("postgres:16-alpine")
.Build();
private AppDbContext _db = null!;
public async Task InitializeAsync()
{
await _postgres.StartAsync();
var options = new DbContextOptionsBuilder<AppDbContext>()
.UseNpgsql(_postgres.GetConnectionString())
.Options;
_db = new AppDbContext(options);
await _db.Database.MigrateAsync();
}
public async Task DisposeAsync()
{
await _db.DisposeAsync();
await _postgres.DisposeAsync();
}
[Fact]
public async Task AddAsync_PersistsOrder()
{
var repo = new SqlOrderRepository(_db);
var order = Order.Create("cust-1", [new OrderItem("SKU-001", 2, 10m)]);
await repo.AddAsync(order, CancellationToken.None);
var found = await repo.FindByIdAsync(order.Id, CancellationToken.None);
found.Should().NotBeNull();
found!.Items.Should().HaveCount(1);
}
}
Test Organization
tests/
MyApp.UnitTests/
Services/
OrderServiceTests.cs
PaymentServiceTests.cs
Validators/
EmailValidatorTests.cs
MyApp.IntegrationTests/
Api/
OrderApiTests.cs
Repositories/
OrderRepositoryTests.cs
MyApp.TestHelpers/
Builders/
OrderBuilder.cs
Fixtures/
DatabaseFixture.cs
Test Data Builders
public sealed class OrderBuilder
{
private string _customerId = "cust-default";
private readonly List<OrderItem> _items = [new("SKU-001", 1, 10m)];
public OrderBuilder WithCustomer(string customerId)
{
_customerId = customerId;
return this;
}
public OrderBuilder WithItem(string sku, int quantity, decimal price)
{
_items.Add(new OrderItem(sku, quantity, price));
return this;
}
public Order Build() => Order.Create(_customerId, _items);
}
// Usage in tests
var order = new OrderBuilder()
.WithCustomer("cust-vip")
.WithItem("SKU-PREMIUM", 3, 99.99m)
.Build();
Common Anti-Patterns
| Anti-Pattern | Fix |
|---|---|
| Testing implementation details | Test behavior and outcomes |
| Shared mutable test state | Fresh instance per test (xUnit does this via constructors) |
Thread.Sleep in async tests | Use Task.Delay with timeout, or polling helpers |
Asserting on ToString() output | Assert on typed properties |
| One giant assertion per test | One logical assertion per test |
| Test names describing implementation | Name by behavior: Method_ExpectedResult_WhenCondition |
Ignoring CancellationToken | Always pass and verify cancellation |
Running Tests
# Run all tests
dotnet test
# Run with coverage
dotnet test --collect:"XPlat Code Coverage"
# Run specific project
dotnet test tests/MyApp.UnitTests/
# Filter by test name
dotnet test --filter "FullyQualifiedName~OrderService"
# Watch mode during development
dotnet watch test --project tests/MyApp.UnitTests/
.NET Backend Development Patterns
Master C#/.NET patterns for building production-grade APIs, MCP servers, and enterprise backends with modern best practices (2024/2025).
When to Use This Skill
- Developing new .NET Web APIs or MCP servers
- Reviewing C# code for quality and performance
- Designing service architectures with dependency injection
- Implementing caching strategies with Redis
- Writing unit and integration tests
- Optimizing database access with EF Core or Dapper
- Configuring applications with IOptions pattern
- Handling errors and implementing resilience patterns
Core Concepts
1. Project Structure (Clean Architecture)
src/
├── Domain/ # Core business logic (no dependencies)
│ ├── Entities/
│ ├── Interfaces/
│ ├── Exceptions/
│ └── ValueObjects/
├── Application/ # Use cases, DTOs, validation
│ ├── Services/
│ ├── DTOs/
│ ├── Validators/
│ └── Interfaces/
├── Infrastructure/ # External implementations
│ ├── Data/ # EF Core, Dapper repositories
│ ├── Caching/ # Redis, Memory cache
│ ├── External/ # HTTP clients, third-party APIs
│ └── DependencyInjection/ # Service registration
└── Api/ # Entry point
├── Controllers/ # Or MinimalAPI endpoints
├── Middleware/
├── Filters/
└── Program.cs
2. Dependency Injection Patterns
// Service registration by lifetime
public static class ServiceCollectionExtensions
{
public static IServiceCollection AddApplicationServices(
this IServiceCollection services,
IConfiguration configuration)
{
// Scoped: One instance per HTTP request
services.AddScoped<IProductService, ProductService>();
services.AddScoped<IOrderService, OrderService>();
// Singleton: One instance for app lifetime
services.AddSingleton<ICacheService, RedisCacheService>();
services.AddSingleton<IConnectionMultiplexer>(_ =>
ConnectionMultiplexer.Connect(configuration["Redis:Connection"]!));
// Transient: New instance every time
services.AddTransient<IValidator<CreateOrderRequest>, CreateOrderValidator>();
// Options pattern for configuration
services.Configure<CatalogOptions>(configuration.GetSection("Catalog"));
services.Configure<RedisOptions>(configuration.GetSection("Redis"));
// Factory pattern for conditional creation
services.AddScoped<IPriceCalculator>(sp =>
{
var options = sp.GetRequiredService<IOptions<PricingOptions>>().Value;
return options.UseNewEngine
? sp.GetRequiredService<NewPriceCalculator>()
: sp.GetRequiredService<LegacyPriceCalculator>();
});
// Keyed services (.NET 8+)
services.AddKeyedScoped<IPaymentProcessor, StripeProcessor>("stripe");
services.AddKeyedScoped<IPaymentProcessor, PayPalProcessor>("paypal");
return services;
}
}
// Usage with keyed services
public class CheckoutService
{
public CheckoutService(
[FromKeyedServices("stripe")] IPaymentProcessor stripeProcessor)
{
_processor = stripeProcessor;
}
}
3. Async/Await Patterns
// ✅ CORRECT: Async all the way down
public async Task<Product> GetProductAsync(string id, CancellationToken ct = default)
{
return await _repository.GetByIdAsync(id, ct);
}
// ✅ CORRECT: Parallel execution with WhenAll
public async Task<(Stock, Price)> GetStockAndPriceAsync(
string productId,
CancellationToken ct = default)
{
var stockTask = _stockService.GetAsync(productId, ct);
var priceTask = _priceService.GetAsync(productId, ct);
await Task.WhenAll(stockTask, priceTask);
return (await stockTask, await priceTask);
}
// ✅ CORRECT: ConfigureAwait in libraries
public async Task<T> LibraryMethodAsync<T>(CancellationToken ct = default)
{
var result = await _httpClient.GetAsync(url, ct).ConfigureAwait(false);
return await result.Content.ReadFromJsonAsync<T>(ct).ConfigureAwait(false);
}
// ✅ CORRECT: ValueTask for hot paths with caching
public ValueTask<Product?> GetCachedProductAsync(string id)
{
if (_cache.TryGetValue(id, out Product? product))
return ValueTask.FromResult(product);
return new ValueTask<Product?>(GetFromDatabaseAsync(id));
}
// ❌ WRONG: Blocking on async (deadlock risk)
var result = GetProductAsync(id).Result; // NEVER do this
var result2 = GetProductAsync(id).GetAwaiter().GetResult(); // Also bad
// ❌ WRONG: async void (except event handlers)
public async void ProcessOrder() { } // Exceptions are lost
// ❌ WRONG: Unnecessary Task.Run for already async code
await Task.Run(async () => await GetDataAsync()); // Wastes thread
4. Configuration with IOptions
// Configuration classes
public class CatalogOptions
{
public const string SectionName = "Catalog";
public int DefaultPageSize { get; set; } = 50;
public int MaxPageSize { get; set; } = 200;
public TimeSpan CacheDuration { get; set; } = TimeSpan.FromMinutes(15);
public bool EnableEnrichment { get; set; } = true;
}
public class RedisOptions
{
public const string SectionName = "Redis";
public string Connection { get; set; } = "localhost:6379";
public string KeyPrefix { get; set; } = "mcp:";
public int Database { get; set; } = 0;
}
// appsettings.json
{
"Catalog": {
"DefaultPageSize": 50,
"MaxPageSize": 200,
"CacheDuration": "00:15:00",
"EnableEnrichment": true
},
"Redis": {
"Connection": "localhost:6379",
"KeyPrefix": "mcp:",
"Database": 0
}
}
// Registration
services.Configure<CatalogOptions>(configuration.GetSection(CatalogOptions.SectionName));
services.Configure<RedisOptions>(configuration.GetSection(RedisOptions.SectionName));
// Usage with IOptions (singleton, read once at startup)
public class CatalogService
{
private readonly CatalogOptions _options;
public CatalogService(IOptions<CatalogOptions> options)
{
_options = options.Value;
}
}
// Usage with IOptionsSnapshot (scoped, re-reads on each request)
public class DynamicService
{
private readonly CatalogOptions _options;
public DynamicService(IOptionsSnapshot<CatalogOptions> options)
{
_options = options.Value; // Fresh value per request
}
}
// Usage with IOptionsMonitor (singleton, notified on changes)
public class MonitoredService
{
private CatalogOptions _options;
public MonitoredService(IOptionsMonitor<CatalogOptions> monitor)
{
_options = monitor.CurrentValue;
monitor.OnChange(newOptions => _options = newOptions);
}
}
5. Result Pattern (Avoiding Exceptions for Flow Control)
// Generic Result type
public class Result<T>
{
public bool IsSuccess { get; }
public T? Value { get; }
public string? Error { get; }
public string? ErrorCode { get; }
private Result(bool isSuccess, T? value, string? error, string? errorCode)
{
IsSuccess = isSuccess;
Value = value;
Error = error;
ErrorCode = errorCode;
}
public static Result<T> Success(T value) => new(true, value, null, null);
public static Result<T> Failure(string error, string? code = null) => new(false, default, error, code);
public Result<TNew> Map<TNew>(Func<T, TNew> mapper) =>
IsSuccess ? Result<TNew>.Success(mapper(Value!)) : Result<TNew>.Failure(Error!, ErrorCode);
public async Task<Result<TNew>> MapAsync<TNew>(Func<T, Task<TNew>> mapper) =>
IsSuccess ? Result<TNew>.Success(await mapper(Value!)) : Result<TNew>.Failure(Error!, ErrorCode);
}
// Usage in service
public async Task<Result<Order>> CreateOrderAsync(CreateOrderRequest request, CancellationToken ct)
{
// Validation
var validation = await _validator.ValidateAsync(request, ct);
if (!validation.IsValid)
return Result<Order>.Failure(
validation.Errors.First().ErrorMessage,
"VALIDATION_ERROR");
// Business rule check
var stock = await _stockService.CheckAsync(request.ProductId, request.Quantity, ct);
if (!stock.IsAvailable)
return Result<Order>.Failure(
$"Insufficient stock: {stock.Available} available, {request.Quantity} requested",
"INSUFFICIENT_STOCK");
// Create order
var order = await _repository.CreateAsync(request.ToEntity(), ct);
return Result<Order>.Success(order);
}
// Usage in controller/endpoint
app.MapPost("/orders", async (
CreateOrderRequest request,
IOrderService orderService,
CancellationToken ct) =>
{
var result = await orderService.CreateOrderAsync(request, ct);
return result.IsSuccess
? Results.Created($"/orders/{result.Value!.Id}", result.Value)
: Results.BadRequest(new { error = result.Error, code = result.ErrorCode });
});
Data Access Patterns
Entity Framework Core
// DbContext configuration
public class AppDbContext : DbContext
{
public DbSet<Product> Products => Set<Product>();
public DbSet<Order> Orders => Set<Order>();
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
// Apply all configurations from assembly
modelBuilder.ApplyConfigurationsFromAssembly(typeof(AppDbContext).Assembly);
// Global query filters
modelBuilder.Entity<Product>().HasQueryFilter(p => !p.IsDeleted);
}
}
// Entity configuration
public class ProductConfiguration : IEntityTypeConfiguration<Product>
{
public void Configure(EntityTypeBuilder<Product> builder)
{
builder.ToTable("Products");
builder.HasKey(p => p.Id);
builder.Property(p => p.Id).HasMaxLength(40);
builder.Property(p => p.Name).HasMaxLength(200).IsRequired();
builder.Property(p => p.Price).HasPrecision(18, 2);
builder.HasIndex(p => p.Sku).IsUnique();
builder.HasIndex(p => new { p.CategoryId, p.Name });
builder.HasMany(p => p.OrderItems)
.WithOne(oi => oi.Product)
.HasForeignKey(oi => oi.ProductId);
}
}
// Repository with EF Core
public class ProductRepository : IProductRepository
{
private readonly AppDbContext _context;
public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)
{
return await _context.Products
.AsNoTracking()
.FirstOrDefaultAsync(p => p.Id == id, ct);
}
public async Task<IReadOnlyList<Product>> SearchAsync(
ProductSearchCriteria criteria,
CancellationToken ct = default)
{
var query = _context.Products.AsNoTracking();
if (!string.IsNullOrWhiteSpace(criteria.SearchTerm))
query = query.Where(p => EF.Functions.Like(p.Name, $"%{criteria.SearchTerm}%"));
if (criteria.CategoryId.HasValue)
query = query.Where(p => p.CategoryId == criteria.CategoryId);
if (criteria.MinPrice.HasValue)
query = query.Where(p => p.Price >= criteria.MinPrice);
if (criteria.MaxPrice.HasValue)
query = query.Where(p => p.Price <= criteria.MaxPrice);
return await query
.OrderBy(p => p.Name)
.Skip((criteria.Page - 1) * criteria.PageSize)
.Take(criteria.PageSize)
.ToListAsync(ct);
}
}
Dapper for Performance
public class DapperProductRepository : IProductRepository
{
private readonly IDbConnection _connection;
public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)
{
const string sql = """
SELECT Id, Name, Sku, Price, CategoryId, Stock, CreatedAt
FROM Products
WHERE Id = @Id AND IsDeleted = 0
""";
return await _connection.QueryFirstOrDefaultAsync<Product>(
new CommandDefinition(sql, new { Id = id }, cancellationToken: ct));
}
public async Task<IReadOnlyList<Product>> SearchAsync(
ProductSearchCriteria criteria,
CancellationToken ct = default)
{
var sql = new StringBuilder("""
SELECT Id, Name, Sku, Price, CategoryId, Stock, CreatedAt
FROM Products
WHERE IsDeleted = 0
""");
var parameters = new DynamicParameters();
if (!string.IsNullOrWhiteSpace(criteria.SearchTerm))
{
sql.Append(" AND Name LIKE @SearchTerm");
parameters.Add("SearchTerm", $"%{criteria.SearchTerm}%");
}
if (criteria.CategoryId.HasValue)
{
sql.Append(" AND CategoryId = @CategoryId");
parameters.Add("CategoryId", criteria.CategoryId);
}
if (criteria.MinPrice.HasValue)
{
sql.Append(" AND Price >= @MinPrice");
parameters.Add("MinPrice", criteria.MinPrice);
}
if (criteria.MaxPrice.HasValue)
{
sql.Append(" AND Price <= @MaxPrice");
parameters.Add("MaxPrice", criteria.MaxPrice);
}
sql.Append(" ORDER BY Name OFFSET @Offset ROWS FETCH NEXT @PageSize ROWS ONLY");
parameters.Add("Offset", (criteria.Page - 1) * criteria.PageSize);
parameters.Add("PageSize", criteria.PageSize);
var results = await _connection.QueryAsync<Product>(
new CommandDefinition(sql.ToString(), parameters, cancellationToken: ct));
return results.ToList();
}
// Multi-mapping for related data
public async Task<Order?> GetOrderWithItemsAsync(int orderId, CancellationToken ct = default)
{
const string sql = """
SELECT o.*, oi.*, p.*
FROM Orders o
LEFT JOIN OrderItems oi ON o.Id = oi.OrderId
LEFT JOIN Products p ON oi.ProductId = p.Id
WHERE o.Id = @OrderId
""";
var orderDictionary = new Dictionary<int, Order>();
await _connection.QueryAsync<Order, OrderItem, Product, Order>(
new CommandDefinition(sql, new { OrderId = orderId }, cancellationToken: ct),
(order, item, product) =>
{
if (!orderDictionary.TryGetValue(order.Id, out var existingOrder))
{
existingOrder = order;
existingOrder.Items = new List<OrderItem>();
orderDictionary.Add(order.Id, existingOrder);
}
if (item != null)
{
item.Product = product;
existingOrder.Items.Add(item);
}
return existingOrder;
},
splitOn: "Id,Id");
return orderDictionary.Values.FirstOrDefault();
}
}
Caching Patterns
Multi-Level Cache with Redis
public class CachedProductService : IProductService
{
private readonly IProductRepository _repository;
private readonly IMemoryCache _memoryCache;
private readonly IDistributedCache _distributedCache;
private readonly ILogger<CachedProductService> _logger;
private static readonly TimeSpan MemoryCacheDuration = TimeSpan.FromMinutes(1);
private static readonly TimeSpan DistributedCacheDuration = TimeSpan.FromMinutes(15);
public async Task<Product?> GetByIdAsync(string id, CancellationToken ct = default)
{
var cacheKey = $"product:{id}";
// L1: Memory cache (in-process, fastest)
if (_memoryCache.TryGetValue(cacheKey, out Product? cached))
{
_logger.LogDebug("L1 cache hit for {CacheKey}", cacheKey);
return cached;
}
// L2: Distributed cache (Redis)
var distributed = await _distributedCache.GetStringAsync(cacheKey, ct);
if (distributed != null)
{
_logger.LogDebug("L2 cache hit for {CacheKey}", cacheKey);
var product = JsonSerializer.Deserialize<Product>(distributed);
// Populate L1
_memoryCache.Set(cacheKey, product, MemoryCacheDuration);
return product;
}
// L3: Database
_logger.LogDebug("Cache miss for {CacheKey}, fetching from database", cacheKey);
var fromDb = await _repository.GetByIdAsync(id, ct);
if (fromDb != null)
{
var serialized = JsonSerializer.Serialize(fromDb);
// Populate both caches
await _distributedCache.SetStringAsync(
cacheKey,
serialized,
new DistributedCacheEntryOptions
{
AbsoluteExpirationRelativeToNow = DistributedCacheDuration
},
ct);
_memoryCache.Set(cacheKey, fromDb, MemoryCacheDuration);
}
return fromDb;
}
public async Task InvalidateAsync(string id, CancellationToken ct = default)
{
var cacheKey = $"product:{id}";
_memoryCache.Remove(cacheKey);
await _distributedCache.RemoveAsync(cacheKey, ct);
_logger.LogInformation("Invalidated cache for {CacheKey}", cacheKey);
}
}
// Stale-while-revalidate pattern
public class StaleWhileRevalidateCache<T>
{
private readonly IDistributedCache _cache;
private readonly TimeSpan _freshDuration;
private readonly TimeSpan _staleDuration;
public async Task<T?> GetOrCreateAsync(
string key,
Func<CancellationToken, Task<T>> factory,
CancellationToken ct = default)
{
var cached = await _cache.GetStringAsync(key, ct);
if (cached != null)
{
var entry = JsonSerializer.Deserialize<CacheEntry<T>>(cached)!;
if (entry.IsStale && !entry.IsExpired)
{
// Return stale data immediately, refresh in background
_ = Task.Run(async () =>
{
var fresh = await factory(CancellationToken.None);
await SetAsync(key, fresh, CancellationToken.None);
});
}
if (!entry.IsExpired)
return entry.Value;
}
// Cache miss or expired
var value = await factory(ct);
await SetAsync(key, value, ct);
return value;
}
private record CacheEntry<TValue>(TValue Value, DateTime CreatedAt)
{
public bool IsStale => DateTime.UtcNow - CreatedAt > _freshDuration;
public bool IsExpired => DateTime.UtcNow - CreatedAt > _staleDuration;
}
}
Testing Patterns
Unit Tests with xUnit and Moq
public class OrderServiceTests
{
private readonly Mock<IOrderRepository> _mockRepository;
private readonly Mock<IStockService> _mockStockService;
private readonly Mock<IValidator<CreateOrderRequest>> _mockValidator;
private readonly OrderService _sut; // System Under Test
public OrderServiceTests()
{
_mockRepository = new Mock<IOrderRepository>();
_mockStockService = new Mock<IStockService>();
_mockValidator = new Mock<IValidator<CreateOrderRequest>>();
// Default: validation passes
_mockValidator
.Setup(v => v.ValidateAsync(It.IsAny<CreateOrderRequest>(), It.IsAny<CancellationToken>()))
.ReturnsAsync(new ValidationResult());
_sut = new OrderService(
_mockRepository.Object,
_mockStockService.Object,
_mockValidator.Object);
}
[Fact]
public async Task CreateOrderAsync_WithValidRequest_ReturnsSuccess()
{
// Arrange
var request = new CreateOrderRequest
{
ProductId = "PROD-001",
Quantity = 5,
CustomerOrderCode = "ORD-2024-001"
};
_mockStockService
.Setup(s => s.CheckAsync("PROD-001", 5, It.IsAny<CancellationToken>()))
.ReturnsAsync(new StockResult { IsAvailable = true, Available = 10 });
_mockRepository
.Setup(r => r.CreateAsync(It.IsAny<Order>(), It.IsAny<CancellationToken>()))
.ReturnsAsync(new Order { Id = 1, CustomerOrderCode = "ORD-2024-001" });
// Act
var result = await _sut.CreateOrderAsync(request);
// Assert
Assert.True(result.IsSuccess);
Assert.NotNull(result.Value);
Assert.Equal(1, result.Value.Id);
_mockRepository.Verify(
r => r.CreateAsync(It.Is<Order>(o => o.CustomerOrderCode == "ORD-2024-001"),
It.IsAny<CancellationToken>()),
Times.Once);
}
[Fact]
public async Task CreateOrderAsync_WithInsufficientStock_ReturnsFailure()
{
// Arrange
var request = new CreateOrderRequest { ProductId = "PROD-001", Quantity = 100 };
_mockStockService
.Setup(s => s.CheckAsync(It.IsAny<string>(), It.IsAny<int>(), It.IsAny<CancellationToken>()))
.ReturnsAsync(new StockResult { IsAvailable = false, Available = 5 });
// Act
var result = await _sut.CreateOrderAsync(request);
// Assert
Assert.False(result.IsSuccess);
Assert.Equal("INSUFFICIENT_STOCK", result.ErrorCode);
Assert.Contains("5 available", result.Error);
_mockRepository.Verify(
r => r.CreateAsync(It.IsAny<Order>(), It.IsAny<CancellationToken>()),
Times.Never);
}
[Theory]
[InlineData(0)]
[InlineData(-1)]
[InlineData(-100)]
public async Task CreateOrderAsync_WithInvalidQuantity_ReturnsValidationError(int quantity)
{
// Arrange
var request = new CreateOrderRequest { ProductId = "PROD-001", Quantity = quantity };
_mockValidator
.Setup(v => v.ValidateAsync(request, It.IsAny<CancellationToken>()))
.ReturnsAsync(new ValidationResult(new[]
{
new ValidationFailure("Quantity", "Quantity must be greater than 0")
}));
// Act
var result = await _sut.CreateOrderAsync(request);
// Assert
Assert.False(result.IsSuccess);
Assert.Equal("VALIDATION_ERROR", result.ErrorCode);
}
}
Integration Tests with WebApplicationFactory
public class ProductsApiTests : IClassFixture<WebApplicationFactory<Program>>
{
private readonly WebApplicationFactory<Program> _factory;
private readonly HttpClient _client;
public ProductsApiTests(WebApplicationFactory<Program> factory)
{
_factory = factory.WithWebHostBuilder(builder =>
{
builder.ConfigureServices(services =>
{
// Replace real database with in-memory
services.RemoveAll<DbContextOptions<AppDbContext>>();
services.AddDbContext<AppDbContext>(options =>
options.UseInMemoryDatabase("TestDb"));
// Replace Redis with memory cache
services.RemoveAll<IDistributedCache>();
services.AddDistributedMemoryCache();
});
});
_client = _factory.CreateClient();
}
[Fact]
public async Task GetProduct_WithValidId_ReturnsProduct()
{
// Arrange
using var scope = _factory.Services.CreateScope();
var context = scope.ServiceProvider.GetRequiredService<AppDbContext>();
context.Products.Add(new Product
{
Id = "TEST-001",
Name = "Test Product",
Price = 99.99m
});
await context.SaveChangesAsync();
// Act
var response = await _client.GetAsync("/api/products/TEST-001");
// Assert
response.EnsureSuccessStatusCode();
var product = await response.Content.ReadFromJsonAsync<Product>();
Assert.Equal("Test Product", product!.Name);
}
[Fact]
public async Task GetProduct_WithInvalidId_Returns404()
{
// Act
var response = await _client.GetAsync("/api/products/NONEXISTENT");
// Assert
Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
}
}
Best Practices
DO
- Use async/await all the way through the call stack
- Inject dependencies through constructor injection
- Use IOptions for typed configuration
- Return Result types instead of throwing exceptions for business logic
- Use CancellationToken in all async methods
- Prefer Dapper for read-heavy, performance-critical queries
- Use EF Core for complex domain models with change tracking
- Cache aggressively with proper invalidation strategies
- Write unit tests for business logic, integration tests for APIs
- Use record types for DTOs and immutable data
DON'T
- Don't block on async with
.Resultor.Wait() - Don't use async void except for event handlers
- Don't catch generic Exception without re-throwing or logging
- Don't hardcode configuration values
- Don't expose EF entities directly in APIs (use DTOs)
- Don't forget
AsNoTracking()for read-only queries - Don't ignore CancellationToken parameters
- Don't create
new HttpClient()manually (use IHttpClientFactory) - Don't mix sync and async code unnecessarily
- Don't skip validation at API boundaries
Common Pitfalls
- N+1 Queries: Use
.Include()or explicit joins - Memory Leaks: Dispose IDisposable resources, use
using - Deadlocks: Don't mix sync and async, use ConfigureAwait(false) in libraries
- Over-fetching: Select only needed columns, use projections
- Missing Indexes: Check query plans, add indexes for common filters
- Timeout Issues: Configure appropriate timeouts for HTTP clients
- Cache Stampede: Use distributed locks for cache population
.NET Development Patterns
Idiomatic C# and .NET patterns for building robust, performant, and maintainable applications.
When to Activate
- Writing new C# code
- Reviewing C# code
- Refactoring existing .NET applications
- Designing service architectures with ASP.NET Core
Core Principles
1. Prefer Immutability
Use records and init-only properties for data models. Mutability should be an explicit, justified choice.
// Good: Immutable value object
public sealed record Money(decimal Amount, string Currency);
// Good: Immutable DTO with init setters
public sealed class CreateOrderRequest
{
public required string CustomerId { get; init; }
public required IReadOnlyList<OrderItem> Items { get; init; }
}
// Bad: Mutable model with public setters
public class Order
{
public string CustomerId { get; set; }
public List<OrderItem> Items { get; set; }
}
2. Explicit Over Implicit
Be clear about nullability, access modifiers, and intent.
// Good: Explicit access modifiers and nullability
public sealed class UserService
{
private readonly IUserRepository _repository;
private readonly ILogger<UserService> _logger;
public UserService(IUserRepository repository, ILogger<UserService> logger)
{
_repository = repository ?? throw new ArgumentNullException(nameof(repository));
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
}
public async Task<User?> FindByIdAsync(Guid id, CancellationToken cancellationToken)
{
return await _repository.FindByIdAsync(id, cancellationToken);
}
}
3. Depend on Abstractions
Use interfaces for service boundaries. Register via DI container.
// Good: Interface-based dependency
public interface IOrderRepository
{
Task<Order?> FindByIdAsync(Guid id, CancellationToken cancellationToken);
Task<IReadOnlyList<Order>> FindByCustomerAsync(string customerId, CancellationToken cancellationToken);
Task AddAsync(Order order, CancellationToken cancellationToken);
}
// Registration
builder.Services.AddScoped<IOrderRepository, SqlOrderRepository>();
Async/Await Patterns
Proper Async Usage
// Good: Async all the way, with CancellationToken
public async Task<OrderSummary> GetOrderSummaryAsync(
Guid orderId,
CancellationToken cancellationToken)
{
var order = await _repository.FindByIdAsync(orderId, cancellationToken)
?? throw new NotFoundException($"Order {orderId} not found");
var customer = await _customerService.GetAsync(order.CustomerId, cancellationToken);
return new OrderSummary(order, customer);
}
// Bad: Blocking on async
public OrderSummary GetOrderSummary(Guid orderId)
{
var order = _repository.FindByIdAsync(orderId, CancellationToken.None).Result; // Deadlock risk
return new OrderSummary(order);
}
Parallel Async Operations
// Good: Concurrent independent operations
public async Task<DashboardData> LoadDashboardAsync(CancellationToken cancellationToken)
{
var ordersTask = _orderService.GetRecentAsync(cancellationToken);
var metricsTask = _metricsService.GetCurrentAsync(cancellationToken);
var alertsTask = _alertService.GetActiveAsync(cancellationToken);
await Task.WhenAll(ordersTask, metricsTask, alertsTask);
return new DashboardData(
Orders: await ordersTask,
Metrics: await metricsTask,
Alerts: await alertsTask);
}
Options Pattern
Bind configuration sections to strongly-typed objects.
public sealed class SmtpOptions
{
public const string SectionName = "Smtp";
public required string Host { get; init; }
public required int Port { get; init; }
public required string Username { get; init; }
public bool UseSsl { get; init; } = true;
}
// Registration
builder.Services.Configure<SmtpOptions>(
builder.Configuration.GetSection(SmtpOptions.SectionName));
// Usage via injection
public class EmailService(IOptions<SmtpOptions> options)
{
private readonly SmtpOptions _smtp = options.Value;
}
Result Pattern
Return explicit success/failure instead of throwing for expected failures.
public sealed record Result<T>
{
public bool IsSuccess { get; }
public T? Value { get; }
public string? Error { get; }
private Result(T value) { IsSuccess = true; Value = value; }
private Result(string error) { IsSuccess = false; Error = error; }
public static Result<T> Success(T value) => new(value);
public static Result<T> Failure(string error) => new(error);
}
// Usage
public async Task<Result<Order>> PlaceOrderAsync(CreateOrderRequest request)
{
if (request.Items.Count == 0)
return Result<Order>.Failure("Order must contain at least one item");
var order = Order.Create(request);
await _repository.AddAsync(order, CancellationToken.None);
return Result<Order>.Success(order);
}
Repository Pattern with EF Core
public sealed class SqlOrderRepository : IOrderRepository
{
private readonly AppDbContext _db;
public SqlOrderRepository(AppDbContext db) => _db = db;
public async Task<Order?> FindByIdAsync(Guid id, CancellationToken cancellationToken)
{
return await _db.Orders
.Include(o => o.Items)
.AsNoTracking()
.FirstOrDefaultAsync(o => o.Id == id, cancellationToken);
}
public async Task<IReadOnlyList<Order>> FindByCustomerAsync(
string customerId,
CancellationToken cancellationToken)
{
return await _db.Orders
.Where(o => o.CustomerId == customerId)
.OrderByDescending(o => o.CreatedAt)
.AsNoTracking()
.ToListAsync(cancellationToken);
}
public async Task AddAsync(Order order, CancellationToken cancellationToken)
{
_db.Orders.Add(order);
await _db.SaveChangesAsync(cancellationToken);
}
}
Middleware and Pipeline
// Custom middleware
public sealed class RequestTimingMiddleware
{
private readonly RequestDelegate _next;
private readonly ILogger<RequestTimingMiddleware> _logger;
public RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)
{
_next = next;
_logger = logger;
}
public async Task InvokeAsync(HttpContext context)
{
var stopwatch = Stopwatch.StartNew();
try
{
await _next(context);
}
finally
{
stopwatch.Stop();
_logger.LogInformation(
"Request {Method} {Path} completed in {ElapsedMs}ms with status {StatusCode}",
context.Request.Method,
context.Request.Path,
stopwatch.ElapsedMilliseconds,
context.Response.StatusCode);
}
}
}
Minimal API Patterns
// Organized with route groups
var orders = app.MapGroup("/api/orders")
.RequireAuthorization()
.WithTags("Orders");
orders.MapGet("/{id:guid}", async (
Guid id,
IOrderRepository repository,
CancellationToken cancellationToken) =>
{
var order = await repository.FindByIdAsync(id, cancellationToken);
return order is not null
? TypedResults.Ok(order)
: TypedResults.NotFound();
});
orders.MapPost("/", async (
CreateOrderRequest request,
IOrderService service,
CancellationToken cancellationToken) =>
{
var result = await service.PlaceOrderAsync(request, cancellationToken);
return result.IsSuccess
? TypedResults.Created($"/api/orders/{result.Value!.Id}", result.Value)
: TypedResults.BadRequest(result.Error);
});
Guard Clauses
// Good: Early returns with clear validation
public async Task<ProcessResult> ProcessPaymentAsync(
PaymentRequest request,
CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(request);
if (request.Amount <= 0)
throw new ArgumentOutOfRangeException(nameof(request.Amount), "Amount must be positive");
if (string.IsNullOrWhiteSpace(request.Currency))
throw new ArgumentException("Currency is required", nameof(request.Currency));
// Happy path continues here without nesting
var gateway = _gatewayFactory.Create(request.Currency);
return await gateway.ChargeAsync(request, cancellationToken);
}
Anti-Patterns to Avoid
| Anti-Pattern | Fix |
|---|---|
async void methods | Return Task (except event handlers) |
.Result or .Wait() | Use await |
catch (Exception) { } | Handle or rethrow with context |
new Service() in constructors | Use constructor injection |
public fields | Use properties with appropriate accessors |
dynamic in business logic | Use generics or explicit types |
Mutable static state | Use DI scoping or ConcurrentDictionary |
string.Format in loops | Use StringBuilder or interpolated string handlers |
F# Testing Patterns
Comprehensive testing patterns for F# applications using xUnit, FsUnit, Unquote, FsCheck, and modern .NET testing practices.
When to Activate
- Writing new tests for F# code
- Reviewing test quality and coverage
- Setting up test infrastructure for F# projects
- Debugging flaky or slow tests
Test Framework Stack
| Tool | Purpose |
|---|---|
| xUnit | Test framework (standard .NET ecosystem choice) |
| FsUnit.xUnit | F#-friendly assertion syntax for xUnit |
| Unquote | Assertion library using F# quotations for clear failure messages |
| FsCheck.xUnit | Property-based testing integrated with xUnit |
| NSubstitute | Mocking .NET dependencies |
| Testcontainers | Real infrastructure in integration tests |
| WebApplicationFactory | ASP.NET Core integration tests |
Unit Tests with xUnit + FsUnit
Basic Test Structure
module OrderServiceTests
open Xunit
open FsUnit.Xunit
[<Fact>]
let ``create sets status to Pending`` () =
let order = Order.create "cust-1" [ validItem ]
order.Status |> should equal Pending
[<Fact>]
let ``confirm changes status to Confirmed`` () =
let order = Order.create "cust-1" [ validItem ]
let confirmed = Order.confirm order
confirmed.Status |> should be (ofCase <@ Confirmed @>)
Assertions with Unquote
Unquote uses F# quotations so failure messages show the full expression that failed, not just "expected X got Y".
module OrderValidationTests
open Xunit
open Swensen.Unquote
[<Fact>]
let ``PlaceOrder returns success when request is valid`` () =
let request = { CustomerId = "cust-123"; Items = [ validItem ] }
let result = OrderService.placeOrder request
test <@ Result.isOk result @>
[<Fact>]
let ``order total sums item prices`` () =
let items = [ { Sku = "A"; Quantity = 2; Price = 10m }
{ Sku = "B"; Quantity = 1; Price = 5m } ]
let total = Order.calculateTotal items
test <@ total = 25m @>
[<Fact>]
let ``validated email rejects empty input`` () =
let result = ValidatedEmail.create ""
test <@ Result.isError result @>
Async Tests
[<Fact>]
let ``PlaceOrder returns success when request is valid`` () = task {
let deps = createTestDeps ()
let request = { CustomerId = "cust-123"; Items = [ validItem ] }
let! result = OrderService.placeOrder deps request
test <@ Result.isOk result @>
}
[<Fact>]
let ``PlaceOrder returns error when items are empty`` () = task {
let deps = createTestDeps ()
let request = { CustomerId = "cust-123"; Items = [] }
let! result = OrderService.placeOrder deps request
test <@ Result.isError result @>
}
Parameterized Tests with Theory
[<Theory>]
[<InlineData("")>]
[<InlineData(" ")>]
let ``PlaceOrder rejects empty customer ID`` (customerId: string) =
let request = { CustomerId = customerId; Items = [ validItem ] }
let result = OrderService.placeOrder request
result |> should be (ofCase <@ Error @>)
[<Theory>]
[<InlineData("", false)>]
[<InlineData("a", false)>]
[<InlineData("user@example.com", true)>]
[<InlineData("user+tag@example.co.uk", true)>]
let ``IsValidEmail returns expected result`` (email: string, expected: bool) =
test <@ EmailValidator.isValid email = expected @>
Property-Based Testing with FsCheck
Using FsCheck.xUnit
open FsCheck
open FsCheck.Xunit
[<Property>]
let ``order total is always non-negative`` (items: NonEmptyList<PositiveInt * decimal>) =
let orderItems =
items.Get
|> List.map (fun (qty, price) ->
{ Sku = "SKU"; Quantity = qty.Get; Price = abs price })
let total = Order.calculateTotal orderItems
total >= 0m
[<Property>]
let ``serialization roundtrips`` (order: Order) =
let json = JsonSerializer.Serialize order
let deserialized = JsonSerializer.Deserialize<Order> json
deserialized = order
Custom Generators
type OrderGenerators =
static member ValidEmail () =
gen {
let! user = Gen.elements [ "alice"; "bob"; "carol" ]
let! domain = Gen.elements [ "example.com"; "test.org" ]
return $"{user}@{domain}"
}
|> Arb.fromGen
[<Property(Arbitrary = [| typeof<OrderGenerators> |])>]
let ``valid emails pass validation`` (email: string) =
EmailValidator.isValid email
Mocking Dependencies
Function Stubs (Preferred)
let createTestDeps () =
let mutable savedOrders = []
{ FindOrder = fun id -> task { return Map.tryFind id testData }
SaveOrder = fun order -> task { savedOrders <- order :: savedOrders }
SendNotification = fun _ -> Task.CompletedTask }
[<Fact>]
let ``PlaceOrder saves the confirmed order`` () = task {
let mutable saved = []
let deps =
{ createTestDeps () with
SaveOrder = fun order -> task { saved <- order :: saved } }
let! _ = OrderService.placeOrder deps validRequest
test <@ saved.Length = 1 @>
}
NSubstitute for .NET Interfaces
open NSubstitute
[<Fact>]
let ``calls repository with correct ID`` () = task {
let repo = Substitute.For<IOrderRepository>()
repo.FindByIdAsync(Arg.Any<Guid>(), Arg.Any<CancellationToken>())
.Returns(Task.FromResult(Some testOrder))
let service = OrderService(repo)
let! _ = service.GetOrder(testOrder.Id, CancellationToken.None)
do! repo.Received(1).FindByIdAsync(testOrder.Id, Arg.Any<CancellationToken>())
}
ASP.NET Core Integration Tests
type OrderApiTests (factory: WebApplicationFactory<Program>) =
interface IClassFixture<WebApplicationFactory<Program>>
let client =
factory.WithWebHostBuilder(fun builder ->
builder.ConfigureServices(fun services ->
services.RemoveAll<DbContextOptions<AppDbContext>>() |> ignore
services.AddDbContext<AppDbContext>(fun options ->
options.UseInMemoryDatabase("TestDb") |> ignore) |> ignore))
.CreateClient()
[<Fact>]
member _.``GET order returns 404 when not found`` () = task {
let! response = client.GetAsync($"/api/orders/{Guid.NewGuid()}")
test <@ response.StatusCode = HttpStatusCode.NotFound @>
}
Test Organization
tests/
MyApp.Tests/
Unit/
OrderServiceTests.fs
PaymentServiceTests.fs
Integration/
OrderApiTests.fs
OrderRepositoryTests.fs
Properties/
OrderPropertyTests.fs
Helpers/
TestData.fs
TestDeps.fs
Common Anti-Patterns
| Anti-Pattern | Fix |
|---|---|
| Testing implementation details | Test behavior and outcomes |
| Mutable shared test state | Fresh state per test |
Thread.Sleep in async tests | Use Task.Delay with timeout, or polling helpers |
Asserting on sprintf output | Assert on typed values and pattern matches |
Ignoring CancellationToken | Always pass and verify cancellation |
| Skipping property-based tests | Use FsCheck for any function with clear invariants |
Related Skills
dotnet-patterns- Idiomatic .NET patterns, dependency injection, and architecturecsharp-testing- C# testing patterns (shared infrastructure like WebApplicationFactory and Testcontainers applies to F# too)
Running Tests
# Run all tests
dotnet test
# Run with coverage
dotnet test --collect:"XPlat Code Coverage"
# Run specific project
dotnet test tests/MyApp.Tests/
# Filter by test name
dotnet test --filter "FullyQualifiedName~OrderService"
# Watch mode during development
dotnet watch test --project tests/MyApp.Tests/
Laravel Development Patterns
Production-grade Laravel architecture patterns for scalable, maintainable applications.
When to Use
- Building Laravel web applications or APIs
- Structuring controllers, services, and domain logic
- Working with Eloquent models and relationships
- Designing APIs with resources and pagination
- Adding queues, events, caching, and background jobs
How It Works
- Structure the app around clear boundaries (controllers -> services/actions -> models).
- Use explicit bindings and scoped bindings to keep routing predictable; still enforce authorization for access control.
- Favor typed models, casts, and scopes to keep domain logic consistent.
- Keep IO-heavy work in queues and cache expensive reads.
- Centralize config in
config/*and keep environments explicit.
Examples
Project Structure
Use a conventional Laravel layout with clear layer boundaries (HTTP, services/actions, models).
Recommended Layout
app/
├── Actions/ # Single-purpose use cases
├── Console/
├── Events/
├── Exceptions/
├── Http/
│ ├── Controllers/
│ ├── Middleware/
│ ├── Requests/ # Form request validation
│ └── Resources/ # API resources
├── Jobs/
├── Models/
├── Policies/
├── Providers/
├── Services/ # Coordinating domain services
└── Support/
config/
database/
├── factories/
├── migrations/
└── seeders/
resources/
├── views/
└── lang/
routes/
├── api.php
├── web.php
└── console.php
Controllers -> Services -> Actions
Keep controllers thin. Put orchestration in services and single-purpose logic in actions.
final class CreateOrderAction
{
public function __construct(private OrderRepository $orders) {}
public function handle(CreateOrderData $data): Order
{
return $this->orders->create($data);
}
}
final class OrdersController extends Controller
{
public function __construct(private CreateOrderAction $createOrder) {}
public function store(StoreOrderRequest $request): JsonResponse
{
$order = $this->createOrder->handle($request->toDto());
return response()->json([
'success' => true,
'data' => OrderResource::make($order),
'error' => null,
'meta' => null,
], 201);
}
}
Routing and Controllers
Prefer route-model binding and resource controllers for clarity.
use Illuminate\Support\Facades\Route;
Route::middleware('auth:sanctum')->group(function () {
Route::apiResource('projects', ProjectController::class);
});
Route Model Binding (Scoped)
Use scoped bindings to prevent cross-tenant access.
Route::scopeBindings()->group(function () {
Route::get('/accounts/{account}/projects/{project}', [ProjectController::class, 'show']);
});
Nested Routes and Binding Names
- Keep prefixes and paths consistent to avoid double nesting (e.g.,
conversationvsconversations). - Use a single parameter name that matches the bound model (e.g.,
{conversation}forConversation). - Prefer scoped bindings when nesting to enforce parent-child relationships.
use App\Http\Controllers\Api\ConversationController;
use App\Http\Controllers\Api\MessageController;
use Illuminate\Support\Facades\Route;
Route::middleware('auth:sanctum')->prefix('conversations')->group(function () {
Route::post('/', [ConversationController::class, 'store'])->name('conversations.store');
Route::scopeBindings()->group(function () {
Route::get('/{conversation}', [ConversationController::class, 'show'])
->name('conversations.show');
Route::post('/{conversation}/messages', [MessageController::class, 'store'])
->name('conversation-messages.store');
Route::get('/{conversation}/messages/{message}', [MessageController::class, 'show'])
->name('conversation-messages.show');
});
});
If you want a parameter to resolve to a different model class, define explicit binding. For custom binding logic, use Route::bind() or implement resolveRouteBinding() on the model.
use App\Models\AiConversation;
use Illuminate\Support\Facades\Route;
Route::model('conversation', AiConversation::class);
Service Container Bindings
Bind interfaces to implementations in a service provider for clear dependency wiring.
use App\Repositories\EloquentOrderRepository;
use App\Repositories\OrderRepository;
use Illuminate\Support\ServiceProvider;
final class AppServiceProvider extends ServiceProvider
{
public function register(): void
{
$this->app->bind(OrderRepository::class, EloquentOrderRepository::class);
}
}
Eloquent Model Patterns
Model Configuration
final class Project extends Model
{
use HasFactory;
protected $fillable = ['name', 'owner_id', 'status'];
protected $casts = [
'status' => ProjectStatus::class,
'archived_at' => 'datetime',
];
public function owner(): BelongsTo
{
return $this->belongsTo(User::class, 'owner_id');
}
public function scopeActive(Builder $query): Builder
{
return $query->whereNull('archived_at');
}
}
Custom Casts and Value Objects
Use enums or value objects for strict typing.
use Illuminate\Database\Eloquent\Casts\Attribute;
protected $casts = [
'status' => ProjectStatus::class,
];
protected function budgetCents(): Attribute
{
return Attribute::make(
get: fn (int $value) => Money::fromCents($value),
set: fn (Money $money) => $money->toCents(),
);
}
Eager Loading to Avoid N+1
$orders = Order::query()
->with(['customer', 'items.product'])
->latest()
->paginate(25);
Query Objects for Complex Filters
final class ProjectQuery
{
public function __construct(private Builder $query) {}
public function ownedBy(int $userId): self
{
$query = clone $this->query;
return new self($query->where('owner_id', $userId));
}
public function active(): self
{
$query = clone $this->query;
return new self($query->whereNull('archived_at'));
}
public function builder(): Builder
{
return $this->query;
}
}
Global Scopes and Soft Deletes
Use global scopes for default filtering and SoftDeletes for recoverable records.
Use either a global scope or a named scope for the same filter, not both, unless you intend layered behavior.
use Illuminate\Database\Eloquent\SoftDeletes;
use Illuminate\Database\Eloquent\Builder;
final class Project extends Model
{
use SoftDeletes;
protected static function booted(): void
{
static::addGlobalScope('active', function (Builder $builder): void {
$builder->whereNull('archived_at');
});
}
}
Query Scopes for Reusable Filters
use Illuminate\Database\Eloquent\Builder;
final class Project extends Model
{
public function scopeOwnedBy(Builder $query, int $userId): Builder
{
return $query->where('owner_id', $userId);
}
}
// In service, repository etc.
$projects = Project::ownedBy($user->id)->get();
Transactions for Multi-Step Updates
use Illuminate\Support\Facades\DB;
DB::transaction(function (): void {
$order->update(['status' => 'paid']);
$order->items()->update(['paid_at' => now()]);
});
Migrations
Naming Convention
- File names use timestamps:
YYYY_MM_DD_HHMMSS_create_users_table.php - Migrations use anonymous classes (no named class); the filename communicates intent
- Table names are
snake_caseand plural by default
Example Migration
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
public function up(): void
{
Schema::create('orders', function (Blueprint $table): void {
$table->id();
$table->foreignId('customer_id')->constrained()->cascadeOnDelete();
$table->string('status', 32)->index();
$table->unsignedInteger('total_cents');
$table->timestamps();
});
}
public function down(): void
{
Schema::dropIfExists('orders');
}
};
Form Requests and Validation
Keep validation in form requests and transform inputs to DTOs.
use App\Models\Order;
final class StoreOrderRequest extends FormRequest
{
public function authorize(): bool
{
return $this->user()?->can('create', Order::class) ?? false;
}
public function rules(): array
{
return [
'customer_id' => ['required', 'integer', 'exists:customers,id'],
'items' => ['required', 'array', 'min:1'],
'items.*.sku' => ['required', 'string'],
'items.*.quantity' => ['required', 'integer', 'min:1'],
];
}
public function toDto(): CreateOrderData
{
return new CreateOrderData(
customerId: (int) $this->validated('customer_id'),
items: $this->validated('items'),
);
}
}
API Resources
Keep API responses consistent with resources and pagination.
$projects = Project::query()->active()->paginate(25);
return response()->json([
'success' => true,
'data' => ProjectResource::collection($projects->items()),
'error' => null,
'meta' => [
'page' => $projects->currentPage(),
'per_page' => $projects->perPage(),
'total' => $projects->total(),
],
]);
Events, Jobs, and Queues
- Emit domain events for side effects (emails, analytics)
- Use queued jobs for slow work (reports, exports, webhooks)
- Prefer idempotent handlers with retries and backoff
Caching
- Cache read-heavy endpoints and expensive queries
- Invalidate caches on model events (created/updated/deleted)
- Use tags when caching related data for easy invalidation
Configuration and Environments
- Keep secrets in
.envand config inconfig/*.php - Use per-environment config overrides and
config:cachein production
Laravel Plugin Discovery
Find, evaluate, and choose healthy Laravel packages using the LaraPlugins.io MCP server.
When to Use
- User wants to find Laravel packages for a specific feature (e.g. "auth", "permissions", "admin panel")
- User asks "what package should I use for..." or "is there a Laravel package for..."
- User wants to check if a package is actively maintained
- User needs to verify Laravel version compatibility
- User wants to assess package health before adding to a project
MCP Requirement
LaraPlugins MCP server must be configured. Add to your ~/.claude.json mcpServers:
"laraplugins": {
"type": "http",
"url": "https://laraplugins.io/mcp/plugins"
}
No API key required — the server is free for the Laravel community.
MCP Tools
The LaraPlugins MCP provides two primary tools:
SearchPluginTool
Search packages by keyword, health score, vendor, and version compatibility.
Parameters:
text_search(string, optional): Keyword to search (e.g. "permission", "admin", "api")health_score(string, optional): Filter by health band —Healthy,Medium,Unhealthy, orUnratedlaravel_compatibility(string, optional): Filter by Laravel version —"5","6","7","8","9","10","11","12","13"php_compatibility(string, optional): Filter by PHP version —"7.4","8.0","8.1","8.2","8.3","8.4","8.5"vendor_filter(string, optional): Filter by vendor name (e.g. "spatie", "laravel")page(number, optional): Page number for pagination
GetPluginDetailsTool
Fetch detailed metrics, readme content, and version history for a specific package.
Parameters:
package(string, required): Full Composer package name (e.g. "spatie/laravel-permission")include_versions(boolean, optional): Include version history in response
How It Works
Finding Packages
When the user wants to discover packages for a feature:
- Use
SearchPluginToolwith relevant keywords - Apply filters for health score, Laravel version, or PHP version
- Review the results with package names, descriptions, and health indicators
Evaluating Packages
When the user wants to assess a specific package:
- Use
GetPluginDetailsToolwith the package name - Review health score, last updated date, Laravel version support
- Check vendor reputation and risk indicators
Checking Compatibility
When the user needs Laravel or PHP version compatibility:
- Search with
laravel_compatibilityfilter set to their version - Or get details on a specific package to see its supported versions
Examples
Example: Find Authentication Packages
SearchPluginTool({
text_search: "authentication",
health_score: "Healthy"
})
Returns packages matching "authentication" with healthy status:
- spatie/laravel-permission
- laravel/breeze
- laravel/passport
- etc.
Example: Find Laravel 12 Compatible Packages
SearchPluginTool({
text_search: "admin panel",
laravel_compatibility: "12"
})
Returns packages compatible with Laravel 12.
Example: Get Package Details
GetPluginDetailsTool({
package: "spatie/laravel-permission",
include_versions: true
})
Returns:
- Health score and last activity
- Laravel/PHP version support
- Vendor reputation (risk score)
- Version history
- Brief description
Example: Find Packages by Vendor
SearchPluginTool({
vendor_filter: "spatie",
health_score: "Healthy"
})
Returns all healthy packages from vendor "spatie".
Filtering Best Practices
By Health Score
| Health Band | Meaning |
|---|---|
Healthy | Active maintenance, recent updates |
Medium | Occasional updates, may need attention |
Unhealthy | Abandoned or infrequently maintained |
Unrated | Not yet assessed |
Recommendation: Prefer Healthy packages for production applications.
By Laravel Version
| Version | Notes |
|---|---|
13 | Latest Laravel |
12 | Current stable |
11 | Still widely used |
10 | Legacy but common |
5-9 | Deprecated |
Recommendation: Match the target project's Laravel version.
Combining Filters
// Find healthy, Laravel 12 compatible packages for permissions
SearchPluginTool({
text_search: "permission",
health_score: "Healthy",
laravel_compatibility: "12"
})
Response Interpretation
Search Results
Each result includes:
- Package name (e.g.
spatie/laravel-permission) - Brief description
- Health status indicator
- Laravel version support badges
Package Details
The detailed response includes:
- Health Score: Numeric or band indicator
- Last Activity: When the package was last updated
- Laravel Support: Version compatibility matrix
- PHP Support: PHP version compatibility
- Risk Score: Vendor trust indicators
- Version History: Recent release timeline
Common Use Cases
| Scenario | Recommended Approach |
|---|---|
| "What package for auth?" | Search "auth" with healthy filter |
| "Is spatie/package still maintained?" | Get details, check health score |
| "Need Laravel 12 packages" | Search with laravel_compatibility: "12" |
| "Find admin panel packages" | Search "admin panel", review results |
| "Check vendor reputation" | Search by vendor, check details |
Best Practices
- Always filter by health — Use
health_score: "Healthy"for production projects - Match Laravel version — Always check
laravel_compatibilitymatches the target project - Check vendor reputation — Prefer packages from known vendors (spatie, laravel, etc.)
- Review before recommending — Use GetPluginDetailsTool for a comprehensive assessment
- No API key needed — The MCP is free, no authentication required
Related Skills
laravel-patterns— Laravel architecture and patternslaravel-tdd— Test-driven development for Laravellaravel-security— Laravel security best practicesdocumentation-lookup— General library documentation lookup (Context7)
Laravel Security Best Practices
Comprehensive security guidelines for Laravel applications to protect against common vulnerabilities.
When to Activate
- Setting up Laravel authentication and authorization (Sanctum, Passport, Jetstream, Breeze)
- Implementing user roles, permissions, and policies
- Configuring production security settings and environment variables
- Reviewing Laravel applications for security vulnerabilities
- Deploying Laravel applications to production
- Writing secure Eloquent queries and migrations
Production Configuration
Essential Production Settings
// config/app.php
'env' => env('APP_ENV', 'production'),
'debug' => (bool) env('APP_DEBUG', false), // CRITICAL: Never true in production
'key' => env('APP_KEY'), // Must be set: php artisan key:generate
// config/session.php
'secure' => env('SESSION_SECURE_COOKIE', true),
'http_only' => true,
'same_site' => 'lax',
// Verify APP_KEY is set at boot
// bootstrap/app.php or a service provider
if (empty(config('app.key'))) {
throw new RuntimeException('APP_KEY is not set. Run: php artisan key:generate');
}
Environment File Security
# NEVER commit .env to version control
# .gitignore already includes .env by default
# Use .env.example with placeholders instead
DB_PASSWORD=
APP_KEY=
SANCTUM_TOKEN_PREFIX=
# Validate required variables at boot
// In AppServiceProvider::boot()
$requiredKeys = ['app.key', 'database.connections.mysql.database', 'database.connections.mysql.username'];
foreach ($requiredKeys as $key) {
if (empty(config($key))) {
throw new RuntimeException("Missing required config key: {$key}");
}
}
HTTPS Enforcement
// AppServiceProvider::boot() or middleware
if (app()->environment('production')) {
URL::forceScheme('https');
request()->server->set('HTTPS', 'on');
}
// config/app.php for trusted proxies (load balancers)
// Use specific IP ranges — * trusts all, allowing X-Forwarded-* spoofing
// AWS: '10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'
'trusted_proxies' => ['10.0.0.0/8', '172.16.0.0/12'],
// Force HTTPS in production via middleware
// app/Http/Middleware/ForceHttps.php
public function handle($request, Closure $next)
{
if (!$request->secure() && app()->environment('production')) {
return redirect()->secure($request->getRequestUri());
}
return $next($request);
}
Authentication
Sanctum (API Token Authentication)
// config/sanctum.php
'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
'%s%s',
'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1',
env('APP_URL') ? ',' . parse_url(env('APP_URL'), PHP_URL_HOST) : ''
)));
'expiration' => 60 * 24, // Token expiration in minutes (null = never)
'token_prefix' => env('SANCTUM_TOKEN_PREFIX', ''),
// Issuing tokens with abilities
$token = $user->createToken('api-token', ['read', 'write'])->plainTextToken;
// Validate abilities on routes
Route::middleware('auth:sanctum')->group(function () {
Route::get('/orders', function () {
// User must have 'read' ability
abort_unless(Auth::user()->tokenCan('read'), 403);
// ...
})->middleware('abilities:read');
Route::post('/orders', function () {
// User must have 'write' ability
abort_unless(Auth::user()->tokenCan('write'), 403);
// ...
})->middleware('abilities:write');
});
Password Security
// config/hashing.php
// Default is bcrypt. Argon2id is stronger.
'bcrypt' => [
'rounds' => env('BCRYPT_ROUNDS', 12), // Increase for stronger hashing
],
'argon' => [
'memory' => 65536,
'threads' => 4,
'time' => 4,
],
// Password validation in RegisterRequest
public function rules(): array
{
return [
'password' => [
'required',
'confirmed',
Password::min(12)
->letters()
->mixedCase()
->numbers()
->symbols()
->uncompromised(), // Checks haveibeenpwned
],
];
}
// Rate limit login attempts
// App\Http\Controllers\Auth\AuthenticatedSessionController
protected function authenticated(Request $request, $user)
{
if ($user->wasRecentlyLockedOut()) {
// Notify user of suspicious login
$user->notify(new SuspiciousLoginNotification($request->ip()));
}
}
Session Management
// config/session.php
'driver' => env('SESSION_DRIVER', 'database'), // database/redis > file
'lifetime' => env('SESSION_LIFETIME', 120),
'expire_on_close' => env('SESSION_EXPIRE_ON_CLOSE', false),
'encrypt' => env('SESSION_ENCRYPT', false),
// Regenerate session on login
// App\Http\Controllers\Auth\AuthenticatedSessionController
public function store(LoginRequest $request): RedirectResponse
{
$request->authenticate();
$request->session()->regenerate(); // CRITICAL: prevents session fixation
return redirect()->intended(RouteServiceProvider::HOME);
}
// Invalidate session on logout
public function destroy(Request $request): RedirectResponse
{
Auth::guard('web')->logout();
$request->session()->invalidate();
$request->session()->regenerateToken();
return redirect('/');
}
Authorization
Gates
// App\Providers\AuthServiceProvider
use App\Models\Post;
use App\Models\User;
use Illuminate\Support\Facades\Gate;
public function boot(): void
{
Gate::define('update-post', function (User $user, Post $post): bool {
return $user->id === $post->user_id;
});
Gate::define('publish-post', function (User $user): bool {
return $user->role === 'editor' || $user->role === 'admin';
});
// Using before() for super-admin override
Gate::before(function (User $user, string $ability): ?bool {
if ($user->role === 'super-admin') {
return true; // Grants all abilities
}
return null; // Fall through to normal checks
});
}
// Usage in controllers
public function update(Request $request, Post $post): RedirectResponse
{
Gate::authorize('update-post', $post);
// Or: $this->authorize('update-post', $post);
// Or: abort_unless(Auth::user()->can('update-post', $post), 403);
// ...
}
Policies
// App\Policies\PostPolicy
class PostPolicy
{
use HandlesAuthorization;
public function viewAny(?User $user): bool
{
return true; // Public listing
}
public function view(?User $user, Post $post): bool
{
return $post->is_published || ($user && $user->id === $post->user_id);
}
public function create(User $user): bool
{
return $user->hasVerifiedEmail(); // Must verify email first
}
public function update(User $user, Post $post): bool
{
return $user->id === $post->user_id;
}
public function delete(User $user, Post $post): bool
{
return $user->id === $post->user_id && $post->created_at->diffInDays(now()) <= 30;
}
public function restore(User $user, Post $post): bool
{
return $user->role === 'admin';
}
public function forceDelete(User $user, Post $post): bool
{
return $user->role === 'super-admin';
}
}
// Register in AuthServiceProvider
protected $policies = [
Post::class => PostPolicy::class,
];
// Controller usage
public function show(Post $post): View
{
$this->authorize('view', $post);
return view('posts.show', compact('post'));
}
// Blade usage
@can('update', $post)
<a href="{{ route('posts.edit', $post) }}">Edit</a>
@endcan
@cannot('update', $post)
<span>You cannot edit this post</span>
@endcannot
Middleware Authorization
// Using middleware in routes
Route::put('/posts/{post}', [PostController::class, 'update'])
->middleware('can:update,post');
Route::get('/posts/create', [PostController::class, 'create'])
->middleware('can:create,App\Models\Post');
// Custom authorization middleware
// app/Http/Middleware/CheckRole.php
class CheckRole
{
public function handle(Request $request, Closure $next, string $role): mixed
{
if (!$request->user() || $request->user()->role !== $role) {
abort(403, 'Unauthorized. This area requires role: ' . $role);
}
return $next($request);
}
}
// Register in Kernel
protected $routeMiddleware = [
'role' => \App\Http\Middleware\CheckRole::class,
];
// Route usage
Route::middleware(['auth', 'role:admin'])->group(function () {
Route::get('/admin', [AdminController::class, 'index']);
});
Eloquent Security
Mass Assignment Protection
// BAD: $guarded = [] allows ALL columns to be mass-assigned
// NEVER use $guarded = [] in production
// GOOD: Whitelist fillable attributes
final class User extends Authenticatable
{
protected $fillable = [
'name',
'email',
'phone',
'avatar',
];
// NEVER add 'role', 'is_admin', 'is_verified' here
}
// GOOD: Explicitly control which fields can be filled in requests
public function store(StoreUserRequest $request): RedirectResponse
{
$user = User::create($request->safe()->only([
'name', 'email', 'phone', 'avatar'
]));
// $request->safe() uses validated data only
// $request->only() is NOT safe on its own without validation rules
}
// BAD: Creating a user with request data directly
User::create($request->all()); // VULNERABLE to mass assignment!
// BETTER: Use DTOs for creation
$user = User::create($request->validated()); // Only validated fields
SQL Injection Prevention
// GOOD: Eloquent automatically parameterizes queries
User::where('email', $userInput)->first();
User::whereRaw('email = ?', [$userInput])->first();
// GOOD: Query Builder also parameterizes
DB::table('users')->where('email', $userInput)->first();
DB::select('SELECT * FROM users WHERE email = ?', [$userInput]);
// BAD: Raw string interpolation
DB::select("SELECT * FROM users WHERE email = '{$userInput}'"); // VULNERABLE!
User::whereRaw("email = '{$userInput}'")->first(); // VULNERABLE!
// BAD: whereRaw/orderByRaw with unescaped input
User::orderByRaw($userInput); // VULNERABLE!
User::groupByRaw($userInput); // VULNERABLE!
// BAD: DB::statement with concatenation
DB::statement("INSERT INTO users (email) VALUES ('{$userInput}')"); // VULNERABLE!
Attribute Casting
final class User extends Authenticatable
{
protected $casts = [
'email_verified_at' => 'datetime',
'is_admin' => 'boolean', // Cast to boolean prevents string injection
'settings' => 'array', // Automatically json_encode/json_decode
'metadata' => 'encrypted:array', // Laravel 11+ encrypted casting
'password' => 'hashed', // Laravel 10+ auto-hashes on set
];
}
Model Security
final class User extends Authenticatable
{
// Hide sensitive attributes from JSON/API responses
protected $hidden = [
'password',
'remember_token',
'two_factor_secret',
'two_factor_recovery_codes',
];
// Append only safe computed attributes
protected $appends = ['full_name']; // safe
// NEVER append sensitive computed data
}
final class Post extends Model
{
// Global scope to filter soft deleted records
use SoftDeletes;
// Prevent N+1 by restricting lazy loading (optional strict mode)
// AppServiceProvider::boot()
// Model::preventLazyLoading(!app()->isProduction());
}
CSRF Protection
Default Protection
// Laravel CSRF is enabled by default via VerifyCsrfToken middleware
// app/Http/Kernel.php (protected $middlewareGroups['web'])
// All POST/PUT/PATCH/DELETE forms must include @csrf
<form method="POST" action="/posts">
@csrf
<input type="text" name="title">
<button type="submit">Create</button>
</form>
Excluding Routes (Carefully)
// app/Http/Middleware/VerifyCsrfToken.php
class VerifyCsrfToken extends Middleware
{
// Only exclude routes that have external CSRF protection (webhooks, etc.)
protected $except = [
'stripe/*', // Stripe webhooks use their own signature verification
// Avoid blanket 'api/*' — stateful Sanctum routes need CSRF.
// Exclude only specific stateless webhook/endpoint routes.
];
}
CSRF with JavaScript
<meta name="csrf-token" content="{{ csrf_token() }}">
<script>
// Axios example (Laravel ships with Axios)
axios.defaults.headers.common['X-CSRF-TOKEN'] = document.querySelector(
'meta[name="csrf-token"]'
).getAttribute('content');
// Fetch example
fetch('/posts', {
method: 'POST',
headers: {
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').getAttribute('content'),
'Content-Type': 'application/json',
},
body: JSON.stringify(data),
});
</script>
XSS Prevention
Blade Templating Security
{{-- SAFE: Auto-escaped by Blade --}}
{{ $userInput }}
{{-- DANGEROUS: Raw output — NEVER use with user input --}}
{!! $userInput !!}
{{-- SAFE: Only use {!! !!} with trusted content you control --}}
{!! $trustedHtmlFromYourServer !!}
{{-- GOOD: Use specific escaping directives --}}
@js($data) {{-- JSON encode for JavaScript --}}
@json($data) {{-- JSON encode in templates --}}
{{-- BAD: Direct user input in raw HTML --}}
<div>{!! $user->bio !!}</div> {{-- VULNERABLE if user provides bio --}}
Safe HTML Handling
// When you must allow some HTML, use a whitelist approach
use HTMLPurifier; // Requires: composer require ezyang/htmlpurifier
public function sanitizeHtml(string $dirty): string
{
$config = \HTMLPurifier_Config::createDefault();
$config->set('HTML.Allowed', 'p,b,i,a[href],ul,ol,li,br');
$config->set('URI.AllowedSchemes', ['http', 'https', 'mailto']);
$purifier = new \HTMLPurifier($config);
return $purifier->purify($dirty);
}
// In blade:
<div>{!! $sanitizedContent !!}</div> {{-- Safe after purification --}}
JavaScript Context Escaping
{{-- SAFE: Blade @js escapes for JavaScript context --}}
<script>
const user = @js($user); // JSON + escaped for JS context
const settings = @json($settings); // Direct JSON encode
</script>
{{-- DANGEROUS: Manual JSON in JS context --}}
<script>
const user = {{ json_encode($user) }}; // NOT escaped for JS!
</script>
HTTP Headers for XSS Protection
// App\Http\Middleware\SecurityHeaders.php
class SecurityHeaders
{
public function handle(Request $request, Closure $next): mixed
{
$response = $next($request);
$response->headers->set('X-Content-Type-Options', 'nosniff');
$response->headers->set('X-Frame-Options', 'DENY');
$response->headers->set('X-XSS-Protection', '1; mode=block');
$response->headers->set('Referrer-Policy', 'strict-origin-when-cross-origin');
$response->headers->set(
'Content-Security-Policy',
"default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'"
);
return $response;
}
}
// Register in kernel
protected $middleware = [
\App\Http\Middleware\SecurityHeaders::class,
];
Input Validation
Form Request Validation
final class StorePostRequest extends FormRequest
{
public function authorize(): bool
{
return $this->user()?->can('create', Post::class) ?? false;
}
public function rules(): array
{
return [
'title' => ['required', 'string', 'max:255'],
'content' => ['required', 'string', 'max:10000'],
'image' => [
'required',
'image',
'mimes:jpg,jpeg,png,gif,webp', // Whitelist specific types
'max:2048', // 2MB max
],
'tags' => ['array'],
'tags.*' => ['integer', 'exists:tags,id'],
];
}
public function messages(): array
{
return [
'title.max' => 'Post title must not exceed 255 characters.',
'image.max' => 'Image must be under 2MB.',
];
}
// Sanitize input after validation
public function validated($key = null, $default = null): mixed
{
$validated = parent::validated();
$validated['title'] = strip_tags($validated['title']);
return $key ? ($validated[$key] ?? $default) : $validated;
}
}
Custom Validation Rules
// app/Rules/StrongPassword.php
class StrongPassword implements Rule
{
public function passes($attribute, $value): bool
{
return preg_match('/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&#^()_\-+=])[A-Za-z\d@$!%*?&#^()_\-+=]{12,}$/', $value);
}
public function message(): string
{
return 'The :attribute must be at least 12 characters with uppercase, lowercase, number, and symbol.';
}
}
// app/Rules/NotBlacklistedDomain.php
class NotBlacklistedDomain implements Rule
{
private array $blacklisted = ['mailinator.com', 'guerrillamail.com'];
public function passes($attribute, $value): bool
{
$domain = substr(strrchr($value, '@'), 1);
return !in_array(strtolower($domain), $this->blacklisted);
}
public function message(): string
{
return 'Email from disposable domains is not allowed.';
}
}
API Security
Rate Limiting
// App/Providers/RouteServiceProvider
protected function configureRateLimiting(): void
{
RateLimiter::for('api', function (Request $request) {
return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});
RateLimiter::for('auth', function (Request $request) {
return Limit::perMinute(5)->by($request->ip())
->response(function () {
return response()->json([
'message' => 'Too many login attempts. Try again in 1 minute.',
], 429);
});
});
RateLimiter::for('uploads', function (Request $request) {
return Limit::perHour(10)->by($request->user()?->id ?? $request->ip())
->response(function () {
return response()->json([
'message' => 'Upload limit reached. Try again later.',
], 429);
});
});
}
// Route usage
Route::middleware(['auth:sanctum', 'throttle:api'])->group(function () {
Route::apiResource('posts', PostController::class);
});
Route::post('/login', [AuthController::class, 'login'])
->middleware('throttle:auth');
API Authentication — Sanctum vs Passport
// Sanctum (recommended for most apps — simple, first-party, SPA)
// config/sanctum.php
'expiration' => 60 * 24, // Tokens expire after 24 hours
'model' => User::class,
// Issuing scoped tokens
$token = $user->createToken('client-name', [
'posts:read',
'posts:write',
])->plainTextToken;
// Middleware scoping
Route::middleware('auth:sanctum')->group(function () {
Route::get('/posts', [PostController::class, 'index'])
->middleware('abilities:posts:read');
Route::post('/posts', [PostController::class, 'store'])
->middleware('abilities:posts:write');
});
// Passport (OAuth2 — for third-party clients or complex auth flows)
// Install: composer require laravel/passport
Passport::tokensExpireIn(now()->addDays(15));
Passport::refreshTokensExpireIn(now()->addDays(30));
Passport::personalAccessTokensExpireIn(now()->addMonths(6));
CORS Configuration
// config/cors.php
return [
'paths' => ['api/*', 'sanctum/csrf-cookie'],
'allowed_methods' => ['*'],
'allowed_origins' => explode(',', env('CORS_ALLOWED_ORIGINS', '')), // Whitelist specific origins
'allowed_origins_patterns' => [],
'allowed_headers' => ['*'],
'exposed_headers' => ['X-Total-Count', 'X-Pagination-Page'],
'max_age' => 0,
'supports_credentials' => true, // Required for Sanctum SPA auth
];
// NEVER: Allow all origins in production unless absolutely necessary
// 'allowed_origins' => ['*'], // Only for truly public APIs
File Upload Security
Validation
public function rules(): array
{
return [
'document' => [
'required',
'file',
'mimes:pdf,doc,docx,xls,xlsx', // Whitelist specific MIME types
'max:10240', // 10MB
'extensions:pdf,doc,docx,xls,xlsx', // Verify extension matches MIME
],
'avatar' => [
'nullable',
'image', // Ensures it's a valid image
'mimes:jpg,jpeg,png,webp',
'max:2048',
'dimensions:min_width=100,min_height=100,max_width=2000,max_height=2000',
],
];
}
Secure Storage
// Store sensitive files on the same private disk used to create temporary URLs.
$path = $request->file('document')->store('documents', 's3');
// Never use the 'public' disk for sensitive documents.
// Use signed URLs for temporary file access
use Illuminate\Support\Facades\Storage;
public function download(Document $document)
{
// Requires route-model binding for Document, a persisted $document->path,
// and a DocumentPolicy::download rule registered with Laravel.
// Authorize against the model that owns the file, never a path taken from the request
$this->authorize('download', $document);
// Generate the temporary signed URL (expires in 15 minutes) only after authorization
$url = Storage::disk('s3')->temporaryUrl($document->path, now()->addMinutes(15));
return redirect($url);
}
// Storage configuration for cloud with encryption
// config/filesystems.php
's3' => [
'driver' => 's3',
'key' => env('AWS_ACCESS_KEY_ID'),
'secret' => env('AWS_SECRET_ACCESS_KEY'),
'region' => env('AWS_DEFAULT_REGION'),
'bucket' => env('AWS_BUCKET'),
'url' => env('AWS_URL'),
'endpoint' => env('AWS_ENDPOINT'),
'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false),
'throw' => false,
'server_side_encryption' => 'AES256', // Encrypt at rest
],
Dependencies and Secrets
Composer Security
# Always audit dependencies in CI
composer audit
# Pin major versions in composer.json
"laravel/framework": "^11.0",
"spatie/laravel-permission": "^6.0"
# Check for abandoned packages
composer why-not
# Keep lock file in version control (it pins exact versions)
# Run `composer update` deliberately, never in CI/CD
Secret Management
# .env file (NEVER commit)
# .gitignore includes .env by default
APP_KEY=base64:abc123...
DB_PASSWORD=secure_password
STRIPE_KEY=sk_live_...
SANCTUM_TOKEN_PREFIX=myapp_
# For production: Use a secret manager
# Deploy with: env $(aws secretsmanager get-secret-value --secret-id prod/db | jq ...) php artisan serve
# Validate secrets at boot (AppServiceProvider::boot)
$secrets = ['services.stripe.key', 'services.stripe.webhook_secret'];
foreach ($secrets as $key) {
if (empty(config($key))) {
Log::critical("Missing secret: {$key}");
}
}
Queue Security
// Define a named rate limiter (typically in AppServiceProvider::boot())
RateLimiter::for('payments', fn () => Limit::perMinute(5));
// Encrypt sensitive job data by implementing the interface
final class ProcessPaymentJob implements ShouldQueue, ShouldBeEncrypted
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public function __construct(
private readonly string $paymentIntentId, // Public IDs are fine
private readonly string $cardFingerprint, // Encrypted via ShouldBeEncrypted
) {}
public function handle(): void
{
// Process payment
}
// Limit retries and delay between attempts
public function retryUntil(): Carbon
{
return now()->addMinutes(5);
}
// Rate limit how many jobs of this type can run
public function middleware(): array
{
return [
new RateLimited('payments'),
];
}
}
Logging Security Events
// config/logging.php
'channels' => [
'security' => [
'driver' => 'single',
'path' => storage_path('logs/security.log'),
'level' => 'warning',
],
],
// Audit log helper
final class SecurityLogger
{
public static function log(string $event, array $context = []): void
{
Log::channel('security')->warning($event, array_merge([
'user_id' => Auth::id(),
'ip' => request()->ip(),
'user_agent' => request()->userAgent(),
'url' => request()->fullUrl(),
'timestamp' => now()->toIso8601String(),
], $context));
}
}
// Usage
SecurityLogger::log('failed_login_attempt', ['email' => $email]);
SecurityLogger::log('password_change');
SecurityLogger::log('role_change', ['target_user' => $targetId, 'new_role' => 'admin']);
SecurityLogger::log('suspicious_activity', ['reason' => 'multiple_attempts_from_different_ips']);
Quick Security Checklist
| Check | Description |
|---|---|
APP_DEBUG=false | Never run with debug enabled in production |
APP_KEY set | Always run php artisan key:generate |
| HTTPS enforced | Force HTTPS in production via middleware or proxy |
$fillable whitelisted | Never use $guarded = [] |
| CSRF active | @csrf on all state-changing forms |
| Sanctum/Passport configured | API authentication with token abilities/scopes |
| Rate limiting applied | Throttle API and auth endpoints |
| Input validation | FormRequest with specific rules, never $request->all() |
| File upload restrictions | Validate MIME types, size, dimensions |
composer audit in CI | Check dependencies for known vulnerabilities |
password_hash / password_verify | Use Laravel's built-in hashing (bcrypt/Argon2) |
| Session regeneration on login | Call $request->session()->regenerate() |
| Security headers middleware | CSP, X-Frame-Options, X-Content-Type-Options |
| Logged security events | Audit log for auth failures, role changes, suspicious activity |
.env not committed | Verify .gitignore includes .env |
Related Skills
laravel-patterns— Laravel architecture, routing, Eloquent, and API patternsbackend-patterns— General backend API and database patternslaravel-tdd— Laravel testing with PHPUnit and Pest
Laravel Testing with TDD
Test-driven development for Laravel applications using PHPUnit, Pest, Laravel factories, and testing helpers.
When to Activate
- Writing new Laravel applications or features
- Implementing API endpoints with Sanctum or Passport authentication
- Testing Eloquent models, relationships, scopes, and accessors
- Setting up testing infrastructure for Laravel projects
- Writing feature tests for HTTP controllers and form requests
- Mocking external services (queues, mail, notifications, HTTP)
TDD Workflow for Laravel
Red-Green-Refactor Cycle
// Step 1: RED — Write a failing test
public function test_a_product_can_be_created(): void
{
$product = Product::factory()->create(['name' => 'Test Product']);
$this->assertDatabaseHas('products', ['name' => 'Test Product']);
}
// Step 2: GREEN — Write the migration, model, and factory
// Step 3: REFACTOR — Improve while keeping tests green
Setup
PHPUnit Configuration
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="vendor/autoload.php"
colors="true">
<testsuites>
<testsuite name="Unit">
<directory suffix="Test.php">tests/Unit</directory>
</testsuite>
<testsuite name="Feature">
<directory suffix="Test.php">tests/Feature</directory>
</testsuite>
</testsuites>
<php>
<env name="APP_ENV" value="testing"/>
<env name="BCRYPT_ROUNDS" value="4"/>
<env name="CACHE_STORE" value="array"/>
<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>
<env name="MAIL_MAILER" value="array"/>
<env name="QUEUE_CONNECTION" value="sync"/>
<env name="SESSION_DRIVER" value="array"/>
</php>
</phpunit>
Base TestCase Setup
namespace Tests;
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
abstract class TestCase extends BaseTestCase
{
protected function setUp(): void
{
parent::setUp();
// Call $this->withoutExceptionHandling() only in tests that
// test non-HTTP exceptions; it suppresses assertStatus() etc.
}
// Helper: Authenticate and return user
protected function actingAsUser(): mixed
{
$user = \App\Models\User::factory()->create();
$this->actingAs($user);
return $user;
}
protected function actingAsAdmin(): mixed
{
$admin = \App\Models\User::factory()->admin()->create();
$this->actingAs($admin);
return $admin;
}
}
Model Factories
// database/factories/UserFactory.php
class UserFactory extends Factory
{
protected static ?string $password = null;
public function definition(): array
{
return [
'name' => fake()->name(),
'email' => fake()->unique()->safeEmail(),
'email_verified_at' => now(),
'password' => static::$password ??= Hash::make('password'),
'remember_token' => Str::random(10),
'role' => 'user',
];
}
public function admin(): static
{
return $this->state(fn (array $attributes) => ['role' => 'admin']);
}
public function unverified(): static
{
return $this->state(fn (array $attributes) => ['email_verified_at' => null]);
}
}
// database/factories/ProductFactory.php
class ProductFactory extends Factory
{
public function definition(): array
{
return [
'name' => fake()->unique()->words(3, true),
'slug' => fn (array $attrs) => Str::slug($attrs['name']),
'description' => fake()->paragraph(),
'price' => fake()->numberBetween(100, 100000),
'stock' => fake()->numberBetween(0, 100),
'is_active' => true,
'user_id' => UserFactory::new(),
];
}
public function outOfStock(): static
{
return $this->state(fn (array $attributes) => ['stock' => 0]);
}
}
Using Factories
$user = User::factory()->create();
$admin = User::factory()->admin()->create();
$product = Product::factory()->create(['user_id' => $user->id]);
$products = Product::factory()->count(10)->create();
$draft = Product::factory()->make(); // Not persisted
// With relationships
$user = User::factory()->has(Product::factory()->count(3))->create();
// Sequences
User::factory()->count(3)->sequence(
['role' => 'admin'], ['role' => 'editor'], ['role' => 'user'],
)->create();
Model Testing
namespace Tests\Unit\Models;
use App\Models\User;
use App\Models\Product;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
class UserTest extends TestCase
{
use RefreshDatabase;
public function test_it_hides_sensitive_attributes(): void
{
$user = User::factory()->create();
$this->assertArrayNotHasKey('password', $user->toArray());
}
public function test_admin_scope_returns_only_admins(): void
{
User::factory()->admin()->create();
User::factory()->count(3)->create();
$this->assertCount(1, User::admin()->get());
}
}
class ProductTest extends TestCase
{
use RefreshDatabase;
public function test_active_scope_filters_correctly(): void
{
Product::factory()->count(3)->create(['is_active' => true]);
Product::factory()->count(2)->create(['is_active' => false]);
$this->assertCount(3, Product::active()->get());
}
public function test_it_belongs_to_a_user(): void
{
$user = User::factory()->create();
$product = Product::factory()->create(['user_id' => $user->id]);
$this->assertTrue($product->user->is($user));
}
}
Feature / HTTP Testing
namespace Tests\Feature\Http\Controllers;
use App\Models\Product;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
class ProductControllerTest extends TestCase
{
use RefreshDatabase;
public function test_guests_are_redirected_to_login(): void
{
$this->get(route('products.create'))->assertRedirect(route('login'));
}
public function test_it_stores_a_new_product(): void
{
$user = User::factory()->create();
$this->actingAs($user);
$response = $this->post(route('products.store'), [
'name' => 'New Product',
'description' => 'Description',
'price' => 2999,
'stock' => 10,
]);
$response->assertRedirect(route('products.index'));
$this->assertDatabaseHas('products', [
'name' => 'New Product',
'user_id' => $user->id,
]);
}
public function test_it_validates_required_fields(): void
{
$this->actingAs(User::factory()->create());
$this->post(route('products.store'), [])
->assertSessionHasErrors(['name', 'price']);
}
public function test_users_cannot_modify_others_products(): void
{
$owner = User::factory()->create();
$attacker = User::factory()->create();
$product = Product::factory()->create(['user_id' => $owner->id]);
$this->actingAs($attacker)
->delete(route('products.destroy', $product))
->assertForbidden();
}
}
JSON API Testing
namespace Tests\Feature\Http\Controllers\Api;
use App\Models\Product;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
class ProductApiTest extends TestCase
{
use RefreshDatabase;
public function test_unauthenticated_requests_are_rejected(): void
{
$this->getJson('/api/products')->assertUnauthorized();
}
public function test_it_lists_paginated_products(): void
{
$user = User::factory()->create();
Product::factory()->count(5)->create(['user_id' => $user->id]);
$response = $this->actingAs($user)->getJson('/api/products');
$response->assertOk();
$response->assertJsonCount(5, 'data');
$response->assertJsonStructure([
'data' => [['id', 'name', 'price']],
'meta' => ['current_page', 'last_page', 'total'],
]);
}
public function test_it_creates_a_product(): void
{
$user = User::factory()->create();
$response = $this->actingAs($user)->postJson('/api/products', [
'name' => 'API Product',
'price' => 4999,
]);
$response->assertCreated();
$response->assertJsonPath('data.name', 'API Product');
}
public function test_users_cannot_delete_others_products(): void
{
$owner = User::factory()->create();
$attacker = User::factory()->create();
$product = Product::factory()->create(['user_id' => $owner->id]);
$this->actingAs($attacker)
->deleteJson("/api/products/{$product->id}")
->assertForbidden();
}
}
Sanctum API Auth Testing
namespace Tests\Feature\Http\Controllers\Api;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Hash;
use Tests\TestCase;
class AuthControllerTest extends TestCase
{
use RefreshDatabase;
public function test_users_can_register(): void
{
$response = $this->postJson('/api/register', [
'name' => 'Test User',
'email' => 'test@example.com',
'password' => 'Password123!',
'password_confirmation' => 'Password123!',
]);
$response->assertCreated();
$response->assertJsonStructure(['data' => ['user', 'token']]);
}
public function test_users_can_login(): void
{
User::factory()->create([
'email' => 'test@example.com',
'password' => Hash::make('Password123!'),
]);
$response = $this->postJson('/api/login', [
'email' => 'test@example.com',
'password' => 'Password123!',
]);
$response->assertOk();
$response->assertJsonStructure(['data' => ['token']]);
}
public function test_users_cannot_login_with_wrong_password(): void
{
User::factory()->create(['email' => 'test@example.com']);
$this->postJson('/api/login', [
'email' => 'test@example.com',
'password' => 'wrong',
])->assertUnprocessable();
}
public function test_token_bearer_authenticates_requests(): void
{
$user = User::factory()->create();
$token = $user->createToken('test')->plainTextToken;
$this->withToken($token)
->getJson('/api/user')
->assertOk()
->assertJsonPath('data.email', $user->email);
}
}
Mocking and Fakes
HTTP Fake
use Illuminate\Support\Facades\Http;
public function test_it_handles_successful_payment(): void
{
Http::fake([
'api.stripe.com/*' => Http::response(['id' => 'pi_123', 'status' => 'succeeded'], 200),
]);
$result = (new PaymentService())->charge(2999);
$this->assertTrue($result->success);
}
public function test_it_handles_gateway_failure(): void
{
Http::fake([
'api.stripe.com/*' => Http::response(['error' => 'card_declined'], 402),
]);
$this->expectException(PaymentFailedException::class);
(new PaymentService())->charge(2999);
}
public function test_it_retries_on_timeout(): void
{
Http::fake([
'api.stripe.com/*' => Http::sequence()
->pushStatus(408)
->pushStatus(200),
]);
$this->assertTrue((new PaymentService())->charge(2999)->success);
}
Mail Fake
Mail::fake();
$order->sendConfirmation();
Mail::assertSent(OrderConfirmation::class, function ($mail) use ($order) {
return $mail->hasTo($order->user->email);
});
Notification Fake
Notification::fake();
$user->notify(new WelcomeUser());
Notification::assertSentTo($user, WelcomeUser::class);
Queue Fake
Queue::fake();
ProcessImage::dispatch($product);
Queue::assertPushed(ProcessImage::class, function ($job) use ($product) {
return $job->product->id === $product->id;
});
Storage Fake
Storage::fake('public');
$file = UploadedFile::fake()->image('photo.jpg', 200, 200);
$response = $this->actingAs($user)->post('/avatar', [
'avatar' => $file,
]);
$response->assertSessionHasNoErrors();
Storage::disk('public')->assertExists('avatars/' . $file->hashName());
Event Fake
Event::fake();
$order->markAsShipped();
Event::assertDispatched(OrderShipped::class, function ($event) use ($order) {
return $event->order->id === $order->id;
});
Artisan Command Tests
public function test_it_sends_newsletters(): void
{
Mail::fake();
User::factory()->count(5)->create(['subscribed' => true]);
$this->artisan('newsletter:send')
->expectsOutput('Sending newsletter to 5 subscribers...')
->assertExitCode(0);
Mail::assertSent(NewsletterMail::class, 5);
}
public function test_it_handles_no_subscribers(): void
{
$this->artisan('newsletter:send')
->expectsOutput('No subscribers found.')
->assertExitCode(0);
}
Authorization Tests
public function test_users_can_update_own_posts(): void
{
$user = User::factory()->create();
$post = Post::factory()->create(['user_id' => $user->id]);
$this->actingAs($user)
->put(route('posts.update', $post), ['title' => 'Updated'])
->assertRedirect();
}
public function test_users_cannot_update_others_posts(): void
{
$post = Post::factory()->create();
$this->actingAs(User::factory()->create())
->put(route('posts.update', $post), ['title' => 'Hacked'])
->assertForbidden();
}
public function test_gate_before_grants_super_admin_full_access(): void
{
$super = User::factory()->create(['role' => 'super-admin']);
$post = Post::factory()->create();
$this->actingAs($super)
->delete(route('posts.destroy', $post))
->assertRedirect();
$this->assertSoftDeleted($post);
}
Pest Feature Tests
<?php
use App\Models\Product;
use App\Models\User;
uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
beforeEach(function () {
$this->user = User::factory()->create();
$this->actingAs($this->user);
});
it('lists products', function () {
Product::factory()->count(3)->create(['user_id' => $this->user->id]);
$this->get(route('products.index'))
->assertOk()
->assertViewHas('products');
});
it('creates a product with valid data', function () {
$this->post(route('products.store'), [
'name' => 'Test Product', 'price' => 1999,
])->assertRedirect();
$this->assertDatabaseHas('products', ['name' => 'Test Product']);
});
it('fails validation without required fields', function () {
$this->post(route('products.store'), [])
->assertSessionHasErrors(['name', 'price']);
});
it('authorizes updates', function () {
$other = User::factory()->create();
$product = Product::factory()->create(['user_id' => $other->id]);
$this->put(route('products.update', $product), ['name' => 'Hacked'])
->assertForbidden();
});
Coverage
# PHPUnit (use clover output for CI threshold checks)
vendor/bin/phpunit --coverage-html coverage --coverage-clover clover.xml
# Pest (built-in threshold support)
vendor/bin/pest --coverage --min=80
Coverage Goals
| Component | Target |
|---|---|
| Models | 95%+ |
| Actions/Services | 90%+ |
| Form Requests | 90%+ |
| Controllers | 85%+ |
| Policies | 95%+ |
| Overall | 80%+ |
Testing Best Practices
DO
- Use factories over manual
create()calls - One logical assertion per test
- Descriptive names:
test_guests_cannot_create_products - Test edge cases and authorization boundaries
- Mock external services with
Http::fake(),Mail::fake() - Use
RefreshDatabasefor clean state
DON'T
- Don't test Laravel internals (trust the framework)
- Don't make tests dependent on each other
- Don't over-mock — mock only service boundaries
- Don't test private methods — test through the public interface
- Don't couple tests to HTML structure
Quick Reference
| Pattern | Usage |
|---|---|
RefreshDatabase | Reset database between tests |
$this->actingAs($user) | Authenticate as user |
$this->withToken($token) | Bearer token auth for APIs |
Model::factory()->create() | Create model with factory |
Model::factory()->count(5)->create() | Create multiple records |
Http::fake([...]) | Mock HTTP calls |
Mail::fake() | Trap sent mail |
Notification::fake() | Trap sent notifications |
Queue::fake() | Trap queued jobs |
Event::fake() | Trap dispatched events |
Storage::fake('public') | Trap file operations |
assertDatabaseHas | Assert DB row exists |
assertSoftDeleted | Assert soft-delete |
assertSessionHasErrors | Assert validation errors |
assertForbidden | Assert 403 status |
Related Skills
laravel-patterns— Laravel architecture, Eloquent, routing, and API patternslaravel-security— Laravel authentication, authorization, and secure codingtdd-workflow— The repo-wide RED -> GREEN -> REFACTOR loopbackend-patterns— General backend API and database patterns
Laravel Verification Loop
Run before PRs, after major changes, and pre-deploy.
When to Use
- Before opening a pull request for a Laravel project
- After major refactors or dependency upgrades
- Pre-deployment verification for staging or production
- Running full lint -> test -> security -> deploy readiness pipeline
How It Works
- Run phases sequentially from environment checks through deployment readiness so each layer builds on the last.
- Environment and Composer checks gate everything else; stop immediately if they fail.
- Linting/static analysis should be clean before running full tests and coverage.
- Security and migration reviews happen after tests so you verify behavior before data or release steps.
- Build/deploy readiness and queue/scheduler checks are final gates; any failure blocks release.
Phase 1: Environment Checks
php -v
composer --version
php artisan --version
- Verify
.envis present and required keys exist - Confirm
APP_DEBUG=falsefor production environments - Confirm
APP_ENVmatches the target deployment (production,staging)
If using Laravel Sail locally:
./vendor/bin/sail php -v
./vendor/bin/sail artisan --version
Phase 1.5: Composer and Autoload
composer validate
composer dump-autoload -o
Phase 2: Linting and Static Analysis
vendor/bin/pint --test
vendor/bin/phpstan analyse
If your project uses Psalm instead of PHPStan:
vendor/bin/psalm
Phase 3: Tests and Coverage
php artisan test
Coverage (CI):
XDEBUG_MODE=coverage php artisan test --coverage
CI example (format -> static analysis -> tests):
vendor/bin/pint --test
vendor/bin/phpstan analyse
XDEBUG_MODE=coverage php artisan test --coverage
Phase 4: Security and Dependency Checks
composer audit
Phase 5: Database and Migrations
php artisan migrate --pretend
php artisan migrate:status
- Review destructive migrations carefully
- Ensure migration filenames follow
Y_m_d_His_*(e.g.,2025_03_14_154210_create_orders_table.php) and describe the change clearly - Ensure rollbacks are possible
- Verify
down()methods and avoid irreversible data loss without explicit backups
Phase 6: Build and Deployment Readiness
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
- Ensure cache warmups succeed in production configuration
- Verify queue workers and scheduler are configured
- Confirm
storage/andbootstrap/cache/are writable in the target environment
Phase 7: Queue and Scheduler Checks
php artisan schedule:list
php artisan queue:failed
If Horizon is used:
php artisan horizon:status
If queue:monitor is available, use it to check backlog without processing jobs:
php artisan queue:monitor default --max=100
Active verification (staging only): dispatch a no-op job to a dedicated queue and run a single worker to process it (ensure a non-sync queue connection is configured).
php artisan tinker --execute="dispatch((new App\\Jobs\\QueueHealthcheck())->onQueue('healthcheck'))"
php artisan queue:work --once --queue=healthcheck
Verify the job produced the expected side effect (log entry, healthcheck table row, or metric).
Only run this on non-production environments where processing a test job is safe.
Examples
Minimal flow:
php -v
composer --version
php artisan --version
composer validate
vendor/bin/pint --test
vendor/bin/phpstan analyse
php artisan test
composer audit
php artisan migrate --pretend
php artisan config:cache
php artisan queue:failed
CI-style pipeline:
composer validate
composer dump-autoload -o
vendor/bin/pint --test
vendor/bin/phpstan analyse
XDEBUG_MODE=coverage php artisan test --coverage
composer audit
php artisan migrate --pretend
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan schedule:list
Limitations
- Verify against current Makepad 2.0 docs; upstream APIs change frequently.
- Do not run bundled scripts without explicit user approval.
When to Use
- Build or diagnose Makepad layouts using the project's installed Splash/script DSL.
- Investigate sizing, flow, clipping, scrolling or overlay-placement problems. First identify the exact Makepad revision and DSL in the project. These sketches assume the imported 2.0-style syntax and are not compiled test fixtures; do not migrate a working application wholesale to match them. See the official Makepad repository for matching widget/source examples.
Makepad 2.0 Layout System
Makepad uses a layout turtle system -- not CSS flexbox, not CSS grid. The turtle walks through children one by one, placing each widget according to two core concepts:
- Walk -- how a widget sizes itself (width, height, margin)
- Layout -- how a container arranges its children (flow, spacing, padding, align) Every container widget (View, SolidView, RoundedView, ScrollYView, etc.) has both Walk properties (its own size) and Layout properties (how it lays out children).
Walk System (Widget Sizing)
Walk controls how an individual widget claims space inside its parent.
width / height
| Syntax | Meaning |
|---|---|
width: Fill | Fill all remaining horizontal space (default) |
width: Fit | Shrink to fit content |
width: 200 | Fixed 200 pixels |
width: Fill{min: 100 max: 500} | Fill with constraints |
width: Fit{max: Abs(300)} | Fit content, capped at 300px |
height: Fill | Fill all remaining vertical space (default) |
height: Fit | Shrink to fit content |
height: 100 | Fixed 100 pixels |
use mod.prelude.widgets.*
// Fill: takes all available width
View{
width: Fill height: Fit
flow: Down
Label{text: "I stretch to fill the width"}
}
// Fit: shrinks to content
View{
width: Fit height: Fit
padding: 10
Label{text: "I am only as wide as this text"}
}
// Fixed: exact pixel size
View{
width: 300 height: 200
Label{text: "I am exactly 300x200 pixels"}
}
// Constrained Fill: fills but within bounds
View{
width: Fill{min: 200 max: 600} height: Fit
flow: Down padding: 16
Label{text: "I fill available space but stay between 200-600px"}
}
CRITICAL: height: Fit on Containers
This is the number one layout bug in Makepad.
The default height is Fill. When your output renders inside a Fit container,
Fill inside Fit creates a circular dependency and resolves to 0 pixels.
A symptom can be zero or unexpected height; inspect the actual parent/child constraints rather than assuming every invisible widget has this cause.
Rule: ALWAYS set height: Fit on every View, SolidView, RoundedView, and similar
container unless the parent has a fixed or Fill height.
// CORRECT -- height: Fit makes the container visible
View{
width: Fill height: Fit
flow: Down padding: 10
Label{text: "I am visible"}
}
// WRONG -- defaults to height: Fill, resolves to 0px, invisible
View{
width: Fill
flow: Down padding: 10
Label{text: "I am invisible (0px tall)"}
}
Exceptions where height: Fill is acceptable:
- Inside a fixed-height parent:
View{
height: 400
View{
height: Fill
Label{text: "I fill the 400px parent"}
}
}
- Inside a
height: Fillchain that ultimately reaches a known size (e.g., Window body). - A ScrollYView needs a bounded viewport.
height: Fillinside a known-height parent is one option; an explicit fixed/constrained height is also valid.
margin
Margin adds space around the outside of a widget.
// Uniform margin on all sides
Label{text: "Hello" margin: 10}
// Selective margin with Inset
Label{
text: "Indented"
margin: Inset{top: 5 bottom: 5 left: 20 right: 20}
}
// Zero margin (note the trailing dot for float literal)
Label{text: "Flush" margin: 0.}
Layout System (Child Arrangement)
Layout controls how a container positions its children.
flow (Direction)
| Syntax | Meaning | CSS Equivalent |
|---|---|---|
flow: Right | Left-to-right, single line (default) | flex-direction: row |
flow: Down | Top-to-bottom, single column | flex-direction: column |
flow: Overlay | Stack children on top of each other | position: absolute stacking |
flow: Flow.Right{wrap: true} | Left-to-right with wrapping | flex-wrap: wrap |
flow: Flow.Down{wrap: true} | Top-to-bottom with wrapping | column wrap |
use mod.prelude.widgets.*
// Vertical stack (most common)
View{
width: Fill height: Fit
flow: Down spacing: 10
Label{text: "First"}
Label{text: "Second"}
Label{text: "Third"}
}
// Horizontal row
View{
width: Fill height: Fit
flow: Right spacing: 10
Label{text: "Left"}
Label{text: "Center"}
Label{text: "Right"}
}
// Overlay -- children stacked on top of each other
View{
width: Fill height: 200
flow: Overlay
Image{width: Fill height: Fill fit: ImageFit.Biggest}
View{
width: Fill height: Fit
align: Align{x: 0.5 y: 1.0}
padding: 10
Label{text: "Caption overlay" draw_text.color: #fff}
}
}
// Wrapping flow -- like a tag cloud or grid of cards
View{
width: Fill height: Fit
flow: Flow.Right{wrap: true}
spacing: 8
padding: 10
Label{text: "Tag 1" margin: 4}
Label{text: "Tag 2" margin: 4}
Label{text: "Tag 3" margin: 4}
Label{text: "Tag 4" margin: 4}
}
spacing
Gap between children. A single number applies uniformly.
View{
flow: Down spacing: 12
Label{text: "12px gap below me"}
Label{text: "12px gap above and below me"}
Label{text: "12px gap above me"}
}
padding
Inner space between the container edge and its children.
// Uniform padding
View{
width: Fill height: Fit
padding: 20
Label{text: "20px padding on all sides"}
}
// Selective padding with Inset
View{
width: Fill height: Fit
padding: Inset{top: 10 bottom: 10 left: 24 right: 24}
Label{text: "Different padding per side"}
}
align (Child Alignment)
Alignment positions children within the remaining space of the container. Values range from 0.0 (start) to 1.0 (end) on each axis.
Alignment Reference Table
| Shorthand | Equivalent | Description |
|---|---|---|
Center | Align{x: 0.5 y: 0.5} | Center on both axes |
HCenter | Align{x: 0.5 y: 0.0} | Horizontal center, top-aligned |
VCenter | Align{x: 0.0 y: 0.5} | Left-aligned, vertical center |
TopLeft | Align{x: 0.0 y: 0.0} | Top-left corner (default) |
Align{x: 1.0 y: 0.0} | -- | Top-right corner |
Align{x: 0.0 y: 1.0} | -- | Bottom-left corner |
Align{x: 1.0 y: 1.0} | -- | Bottom-right corner |
Align{x: 0.5 y: 1.0} | -- | Bottom center |
use mod.prelude.widgets.*
// Center everything
View{
width: Fill height: 300
align: Center
Label{text: "I am centered"}
}
// Horizontal center only (children flow from top)
View{
width: Fill height: Fit
flow: Down
align: HCenter
Label{text: "I am horizontally centered"}
}
// Vertically center children in a horizontal row
View{
width: Fill height: 60
flow: Right spacing: 10
align: Align{y: 0.5}
Label{text: "Vertically centered" draw_text.text_style.font_size: 14}
Label{text: "Small text" draw_text.text_style.font_size: 9}
}
clip_x / clip_y
Controls whether overflowing content is clipped.
// Clip overflow (default behavior)
View{
width: 200 height: 100
clip_x: true
clip_y: true
Label{text: "Very long text that will be clipped at the container boundary"}
}
// Allow overflow to be visible
View{
width: 200 height: 100
clip_x: false
clip_y: false
Label{text: "This text can overflow beyond the container"}
}
Important boundary: clip_x: false / clip_y: false only allow a local child to
paint outside its parent. They do NOT turn that child into a true window-level overlay.
If the UI element is a popup/menu/tooltip that should float independently of the local
layout tree, use a top-level Modal/overlay owner instead of relying on local overflow.
Overlay Popups: walk.abs_pos vs margin
For popup-style positioning inside an overlay (Modal, tooltip layer, popup owner),
prefer walk.abs_pos over runtime margin tweaks.
marginis layout spacing. It is best for nudging normal flow children.walk.abs_posis an explicit turtle anchor for overlay-style placement.button.area().clipped_rect(cx)gives you the trigger's actual screen-space rect, includingview_shiftand clipping.- For overlay content, compute the popup's absolute screen-space target, then write
that into
popup.walk.abs_pos = Some(dvec2(x, y)).
// Sketch: define popup_height from measured content; clamp/flip at viewport edges.
// Verify the overlay's coordinate space and convert screen coordinates if required.
let button_rect = button.area().clipped_rect(cx);
let popup_pos = dvec2(button_rect.pos.x, button_rect.pos.y - popup_height);
if let Some(mut popup) = self.view(cx, ids!(popup)).borrow_mut() {
popup.walk.abs_pos = Some(popup_pos);
}
Rule of thumb:
- Popup inside normal layout tree, only slight overflow needed: local child +
clip_x/clip_y: false - Popup anchored to a button but visually outside the component: top-level overlay +
walk.abs_pos
Common mistake: Using script_apply_eval! to push margin.top / margin.left on
overlay content and expecting stable popup coordinates. That often produces misleading
results because you are still negotiating with layout, not explicitly anchoring the popup.
Inset Syntax
The Inset type is used for both padding and margin. It supports two forms:
// Bare number -- uniform on all four sides
padding: 10
margin: 5
// Inset struct -- specify individual sides
padding: Inset{top: 10 bottom: 10 left: 20 right: 20}
margin: Inset{top: 0 bottom: 8 left: 0 right: 0}
// Zero (use trailing dot for float literal)
margin: 0.
// You can omit sides you do not need -- they default to 0
padding: Inset{left: 16 right: 16}
Both padding and margin accept the same Inset syntax. Padding is inside the
container, margin is outside.
Scrollable Containers
Makepad provides three scrollable view variants. They inherit all View properties and add scrollbar behavior.
| Widget | Scroll Direction | Typical Use |
|---|---|---|
ScrollYView | Vertical only | Long lists, page content |
ScrollXView | Horizontal only | Wide tables, timelines |
ScrollXYView | Both axes | Maps, canvases, large content |
use mod.prelude.widgets.*
// Vertical scrolling -- the most common pattern
// Note: ScrollYView uses height: Fill (not Fit) to define the scroll viewport
ScrollYView{
width: Fill height: Fill
flow: Down padding: 10 spacing: 8
Label{text: "Item 1"}
Label{text: "Item 2"}
Label{text: "Item 3"}
Label{text: "Item 4"}
Label{text: "Item 5"}
Label{text: "Item 6"}
}
// Horizontal scrolling
ScrollXView{
width: Fill height: 60
flow: Right spacing: 10 padding: 10
align: Align{y: 0.5}
Label{text: "Tab 1"}
Label{text: "Tab 2"}
Label{text: "Tab 3"}
Label{text: "Tab 4"}
}
// Both-axis scrolling
ScrollXYView{
width: Fill height: Fill
Label{text: "Large content that can be scrolled in both directions"}
}
When to use which:
ScrollYView-- page body, lists, vertical content. This is what you need 90% of the time.ScrollXView-- horizontal tab bars, code scrolling, timeline views.ScrollXYView-- 2D canvases, maps, spreadsheet-style content.
Important: Scrollable views use height: Fill (not height: Fit) because they
need a fixed viewport to scroll within. The content inside grows beyond the viewport.
Filler (Spacer Widget)
Filler{} is equivalent to View{width: Fill height: Fill}. It pushes siblings apart.
Critical rule: Only use Filler between width: Fit siblings.
Do NOT use Filler{} next to a width: Fill sibling. Both compete for remaining space,
splitting it 50/50 and clipping text.
use mod.prelude.widgets.*
// CORRECT: Filler between Fit siblings
View{
width: Fill height: Fit
flow: Right
align: Align{y: 0.5}
Label{text: "Left side"}
Filler{}
Label{text: "Right side"}
}
// WRONG: Filler next to a Fill sibling -- text gets clipped
View{
width: Fill height: Fit
flow: Right
Label{width: Fill text: "This gets clipped to half width"}
Filler{}
Label{text: "Tag"}
}
// CORRECT alternative: width: Fill naturally pushes Fit siblings
View{
width: Fill height: Fit
flow: Right
View{
width: Fill height: Fit
flow: Down
Label{text: "Title takes remaining space"}
Label{text: "Subtitle"}
}
Label{text: "Tag"}
}
Common Layout Patterns
Vertical Page Layout
use mod.prelude.widgets.*
View{
width: Fill height: Fit
flow: Down spacing: 16 padding: 20
Label{text: "Page Title" draw_text.color: #fff draw_text.text_style.font_size: 18}
Label{text: "Subtitle text" draw_text.color: #aaa draw_text.text_style.font_size: 12}
Hr{}
Label{text: "Body content goes here" draw_text.color: #ddd}
}
Horizontal Toolbar
use mod.prelude.widgets.*
SolidView{
width: Fill height: 44
flow: Right spacing: 8
padding: Inset{left: 12 right: 12}
align: Align{y: 0.5}
draw_bg.color: #2a2a3d
ButtonFlatter{text: "File"}
ButtonFlatter{text: "Edit"}
ButtonFlatter{text: "View"}
Filler{}
ButtonFlat{text: "Run"}
}
Extended reference
See references/extended-guide.md for the full upstream document.
When to Use
- Choose Makepad widgets or diagnose widget properties, list virtualization, dialogs or custom drawing in an existing Makepad project.
- Establish the exact dependency revision and DSL first; these imported dev-branch notes are not a stable 2.0 API contract or a compiled example suite. Check the matching official Makepad source before changing a working project.
Makepad 2.0 Widget Catalog Skill
Version: makepad-widgets (dev branch) | Last Updated: 2026-03-03
Overview
Makepad 2.0 provides a rich set of built-in widgets for building UIs. These notes describe a Splash/script_mod-style project; do not assume they apply to every released or older Live DSL project.
Documentation
Refer to the local files for detailed documentation:
./references/widget-catalog.md- Complete widget list with properties./references/widget-advanced.md- Advanced patterns: PortalList, Dock, custom widgets, MapView
IMPORTANT: Documentation Completeness Check
Before answering questions, Claude MUST:
- Read the relevant reference file(s) listed above
- Incorporate reference content into the answer
Widget Categories Quick Reference
Containers (Layout)
| Widget | Description | Key Properties |
|---|---|---|
View | Basic container (transparent) | width, height, flow, spacing, padding, align |
SolidView | View with solid background | + show_bg: true, draw_bg.color |
RoundedView | View with rounded corners | + draw_bg.border_radius |
RoundedAllView | Per-corner radii | Check the vec4 draw_bg.border_radius API in the installed revision |
GradientXView | Horizontal gradient bg | + draw_bg colors |
GradientYView | Vertical gradient bg | + draw_bg colors |
ScrollXView | Horizontal scrolling | scroll property |
ScrollYView | Vertical scrolling | scroll property |
ScrollXYView | Both-axis scrolling | scroll property |
Text Widgets
| Widget | Description | Key Properties |
|---|---|---|
Label | Single/multi-line text | text, draw_text.color, draw_text.text_style.font_size |
H1 - H4 | Heading levels | text (pre-styled) |
P | Paragraph text | text |
TextInput | Editable text field | text, empty_text, is_password, is_read_only, is_numeric_only |
Markdown | Markdown renderer | body |
Html | HTML renderer | body |
LinkLabel | Clickable link text | text, url |
Buttons
| Widget | Description | Key Properties |
|---|---|---|
Button | Standard button | text |
ButtonFlat | Flat style button | text |
ButtonFlatter | Minimal button | text |
Toggles
| Widget | Description | Key Properties |
|---|---|---|
CheckBox | Check box | text, active |
Toggle | Toggle switch | text, active |
RadioButton | Radio button | text, active |
Input Widgets
| Widget | Description | Key Properties |
|---|---|---|
Slider | Horizontal slider | min, max, step, default, precision |
DropDown | Dropdown select | labels: ["a", "b", "c"] |
Media
| Widget | Description | Key Properties |
|---|---|---|
Image | Image display | src, fit (Stretch/Horizontal/Vertical/Smallest/Biggest/Size) |
Svg | External SVG file renderer | draw_svg.svg (crate_resource/http_resource), animating, draw_svg.color |
Icon | SVG icon (tinted) | draw_icon.svg, draw_icon.color, icon_walk |
Vector | Inline vector graphics | viewbox, Path{d: "..."} |
LoadingSpinner | Loading indicator | color, rotation_speed |
MapView | Map widget | center_lon, center_lat, zoom (MUST use fixed height!) |
Layout Helpers
| Widget | Description | Usage |
|---|---|---|
Hr | Horizontal rule | Divider line |
Vr | Vertical rule | Vertical divider |
Filler | Flexible space | Push siblings apart (use between Fit siblings only!) |
Splitter | Resizable split | axis: Horizontal/Vertical, a/b children |
FoldHeader | Collapsible section | header + body children |
Lists
| Widget | Description | Usage |
|---|---|---|
PortalList | Virtualized list | For large lists (100+ items), only renders visible items |
FlatList | Simple list | For small lists, renders all items |
Navigation
| Widget | Description | Control |
|---|---|---|
Modal | Modal dialog | .open(cx) / .close(cx) from Rust |
Tooltip | Tooltip popup | Hover-triggered |
PopupNotification | Toast notification | Timed display |
SlidePanel | Sliding panel | side (verify installed API) |
ExpandablePanel | Expandable area | open/close |
PageFlip | Page switcher | active_page: page_name |
StackNavigation | Stack nav | push/pop pages |
Dock System
| Widget | Description |
|---|---|
Dock | Tab container system |
DockSplitter | Dock split panels |
DockTabs | Tab bar |
DockTab | Individual tab |
The snippets are illustrative and omit app registration/event wiring. Numeric input and password masking are presentation controls, not validation, encryption or authorization. Treat external Markdown/HTML, SVG, image URLs and map tiles as untrusted resources; restrict allowed schemes/hosts, bound decoding, honor asset licenses/attribution and verify privacy before enabling network fetches. Do not log text-input contents. Test keyboard navigation, focus return/trapping for modals, readable contrast and touch behavior.
Critical Rules
1. height: Fit on Containers
// Possible Fill/Fit constraint mismatch; inspect the parent chain
View{ flow: Down Label{text: "Invisible"} }
// CORRECT
View{ height: Fit flow: Down Label{text: "Visible"} }
2. new_batch for Colored Containers with Text
// WRONG - text behind background
RoundedView{ draw_bg.color: #333 Label{text: "Invisible"} }
// CORRECT
RoundedView{ new_batch: true draw_bg.color: #333 Label{text: "Visible"} }
3. Named Children with :=
// Named (addressable, overridable)
title := Label{text: "Hello"}
// Static (not addressable)
Label{text: "Hello"}
4. Label Default Color is White
// Default text is white (#fff) - set color for light backgrounds
Label{text: "Dark text" draw_text.color: #333}
5. MapView MUST Have Fixed Height
// WRONG
MapView{ width: Fill height: Fill }
// CORRECT
View{ new_batch: true width: Fill height: 400
MapView{ width: Fill height: 400 center_lat: 40.7 center_lon: -73.9 zoom: 14.0 }
}
6. Label Does NOT Support Animator
// WRONG (silently ignored)
Label{ animator: Animator{...} }
// CORRECT - wrap in View
View{ animator: Animator{...} Label{text: "Animated"} }
Common Widget Patterns
Card
RoundedView{
width: Fill height: Fit
padding: 16
new_batch: true
draw_bg.color: #2a2a3d
draw_bg.border_radius: 8.0
flow: Down spacing: 8
title := Label{text: "Title" draw_text.color: #fff draw_text.text_style.font_size: 16}
body := Label{text: "Content" draw_text.color: #aaa}
}
Form Input
View{
width: Fill height: Fit
flow: Down spacing: 4
Label{text: "Email" draw_text.color: #aaa draw_text.text_style.font_size: 11}
email_input := TextInput{
width: Fill height: 36
empty_text: "Enter email..."
}
}
Scrollable List
ScrollYView{
width: Fill height: Fill
flow: Down spacing: 4
new_batch: true
on_render: || {
for i, item in items {
ItemTemplate{label.text: item.name}
}
}
}
Best Practices
- Use
height: Fiton every container unless you want Fill or fixed pixels - Use
new_batch: trueon any View with background color + text children - Use
:=for children you need to reference or override - Use theme colors (
theme.color_*) instead of hardcoded colors - Use
PortalListfor large lists (virtualizes rendering) - Use
ScrollYViewfor scrollable content areas - Use
RoundedViewfor cards and containers (has border_radius)
Examples
User: Apply this skill to my current task.
Assistant: Follow the workflow in this skill, cite limitations, and ask before risky steps.
Limitations
- Imported upstream skill; verify credentials, permissions, and safety boundaries before execution.
- Does not replace environment-specific validation, testing, or maintainer review.
Supporting material availability
This catalog copy contains the inline guidance below, but does not include the following supporting paths. They are external prerequisites, not bundled files:
./references/app-structure.md./references/event-handling.md
Obtain the required material from the declared upstream source, or from a user-provided installation of that source. Resolve each path relative to that installation, inspect its contents, and verify any applicable license and execution prerequisites. Do not run a command or claim a referenced procedure was followed until its required file exists. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user’s authorized scope; report any dependent step as unavailable.
Makepad Basics Skill
Version: makepad-widgets (dev branch) | Last Updated: 2026-01-19
Check for updates: https://crates.io/crates/makepad-widgets
You are an expert at the Rust makepad-widgets crate. Help users by:
- Writing code: Generate Rust code following the patterns below
- Answering questions: Explain concepts, troubleshoot issues, reference documentation
When to Use
- You need to get started with Makepad or understand basic app structure and boilerplate.
- The task involves project setup,
live_design!,app_main!, or first-screen application wiring. - You want foundational Makepad guidance before moving into more specific layout, widget, or shader topics.
Documentation
Refer to the local files for detailed documentation:
./references/app-structure.md- Complete app boilerplate and structure./references/event-handling.md- Event handling patterns
IMPORTANT: Documentation Completeness Check
Before answering questions, Claude MUST:
- Read the relevant reference file(s) listed above
- If file read fails or file is empty:
- Report missing reference files; no sync-crate-skills command is bundled and --force is not an automatic fallback.
- Still answer based on SKILL.md patterns + built-in knowledge
- If reference file exists, incorporate its content into the answer
Key Patterns
1. Basic App Structure
use makepad_widgets::*;
live_design! {
use link::theme::*;
use link::shaders::*;
use link::widgets::*;
App = {{App}} {
ui: <Root> {
main_window = <Window> {
body = <View> {
width: Fill, height: Fill
flow: Down
<Label> { text: "Hello Makepad!" }
}
}
}
}
}
app_main!(App);
#[derive(Live, LiveHook)]
pub struct App {
#[live] ui: WidgetRef,
}
impl LiveRegister for App {
fn live_register(cx: &mut Cx) {
crate::makepad_widgets::live_design(cx);
}
}
impl AppMain for App {
fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
self.ui.handle_event(cx, event, &mut Scope::empty());
}
}
2. Cargo.toml Setup
[package]
name = "my_app"
version = "0.1.0"
edition = "2024"
[dependencies]
makepad-widgets = { git = "https://github.com/makepad/makepad", rev = "<reviewed-full-commit>" }
Examples target a historical dev API and require a verified Rust/toolchain/platform setup; replace the commit placeholder before use. Button/label/input examples require matching named widgets in live_design and the pinned revision's event API. Platform package lists and web tooling are illustrative, not a current install guarantee.
3. Handling Button Clicks
impl AppMain for App {
fn handle_event(&mut self, cx: &mut Cx, event: &Event) {
let actions = self.ui.handle_event(cx, event, &mut Scope::empty());
if self.ui.button(id!(my_button)).clicked(&actions) {
log!("Button clicked!");
}
}
}
4. Accessing and Modifying Widgets
// Get widget references
let label = self.ui.label(id!(my_label));
label.set_text("Updated text");
let input = self.ui.text_input(id!(my_input));
let text = input.text();
API Reference Table
| Macro/Type | Description | Example |
|---|---|---|
live_design! | Defines UI in DSL | live_design! { App = {{App}} { ... } } |
app_main! | Entry point macro | app_main!(App); |
#[derive(Live)] | Derive live data | #[derive(Live, LiveHook)] |
WidgetRef | Reference to UI tree | #[live] ui: WidgetRef |
Cx | Context for rendering | fn handle_event(&mut self, cx: &mut Cx, ...) |
id!() | Widget ID macro | self.ui.button(id!(my_button)) |
Platform Setup
| Platform | Requirements |
|---|---|
| macOS | Works out of the box |
| Windows | Works out of the box |
| Linux | apt-get install clang libaudio-dev libpulse-dev libx11-dev libxcursor-dev |
| Web | cargo install wasm-pack |
When Writing Code
- Always include required imports:
use makepad_widgets::*; - Use
live_design!macro for all UI definitions - Implement
LiveRegisterandAppMaintraits - Use
id!()macro for widget references - Handle events through
handle_eventmethod
When Answering Questions
- Explain supported live-design reload for the pinned tooling; do not promise every DSL/Rust change reloads without compilation
- Makepad is GPU-first - all rendering is shader-based
- Cross-platform: same code runs on Android, iOS, Linux, macOS, Windows, Web
- Recommend UI Zoo example for widget exploration
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Supporting material availability
This catalog copy contains the inline guidance below, but does not include the following supporting paths. They are external prerequisites, not bundled files:
./references/event-system.md./references/action-system.md
Ask for the original supporting material or an existing installation before using a step that depends on these paths; this catalog does not identify a verified download source for them. Resolve each path relative to that installation, inspect its contents, and verify any applicable license and execution prerequisites. Do not run a command or claim a referenced procedure was followed until its required file exists. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user’s authorized scope; report any dependent step as unavailable.
Makepad Event/Action Skill
Version: makepad-widgets (dev branch) | Last Updated: 2026-01-19
Check for updates: https://crates.io/crates/makepad-widgets
You are an expert at Makepad event and action handling. Help users by:
- Handling events: Mouse, keyboard, touch, lifecycle events
- Creating actions: Widget-to-parent communication
- Event flow: Understanding event propagation
When to Use
- You need to handle input, lifecycle, or UI interaction events in Makepad.
- The task involves
handle_event,Eventvariants,Hitprocessing, or widget action propagation. - You need to design or debug Makepad event/action flow between widgets and parents.
Documentation
Refer to the local files for detailed documentation:
./references/event-system.md- Event enum and handling./references/action-system.md- Action trait and patterns
IMPORTANT: Documentation Completeness Check
Before answering questions, Claude MUST:
- Read the relevant reference file(s) listed above
- If file read fails or file is empty:
- Report the missing reference and the resulting coverage limit; do not recommend an unavailable slash command or claim the missing procedure was followed
- Use independent inline patterns only after checking their compatibility with the project's pinned crate; identify unverified APIs
- If reference file exists, incorporate its content into the answer
Event Enum (Key Variants)
pub enum Event {
// Lifecycle
Startup,
Shutdown,
Foreground,
Background,
Resume,
Pause,
// Drawing
Draw(DrawEvent),
LiveEdit,
// Window
WindowGotFocus(WindowId),
WindowLostFocus(WindowId),
WindowGeomChange(WindowGeomChangeEvent),
WindowClosed(WindowClosedEvent),
// Mouse
MouseDown(MouseDownEvent),
MouseMove(MouseMoveEvent),
MouseUp(MouseUpEvent),
Scroll(ScrollEvent),
// Touch
TouchUpdate(TouchUpdateEvent),
// Keyboard
KeyDown(KeyEvent),
KeyUp(KeyEvent),
TextInput(TextInputEvent),
TextCopy(TextClipboardEvent),
// Timer
Timer(TimerEvent),
NextFrame(NextFrameEvent),
// Network
HttpResponse(HttpResponse),
// Widget Actions
Actions(ActionsBuf),
}
Handling Events in Widgets
impl Widget for MyWidget {
fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {
// Check if event hits this widget's area
match event.hits(cx, self.area()) {
Hit::FingerDown(fe) => {
// Mouse/touch down on this widget
cx.action(MyWidgetAction::Pressed);
}
Hit::FingerUp(fe) => {
if fe.is_over {
// Released while still over widget = click
cx.action(MyWidgetAction::Clicked);
}
}
Hit::FingerHoverIn(_) => {
self.animator_play(cx, id!(hover.on));
}
Hit::FingerHoverOut(_) => {
self.animator_play(cx, id!(hover.off));
}
Hit::KeyDown(ke) => {
if ke.key_code == KeyCode::Return {
cx.action(MyWidgetAction::Submitted);
}
}
_ => {}
}
}
}
Hit Enum
pub enum Hit {
// Finger/Mouse
FingerDown(FingerDownEvent),
FingerUp(FingerUpEvent),
FingerMove(FingerMoveEvent),
FingerHoverIn(FingerHoverEvent),
FingerHoverOver(FingerHoverEvent),
FingerHoverOut(FingerHoverEvent),
FingerLongPress(FingerLongPressEvent),
// Keyboard
KeyDown(KeyEvent),
KeyUp(KeyEvent),
KeyFocus,
KeyFocusLost,
TextInput(TextInputEvent),
TextCopy,
// Nothing
Nothing,
}
Action System
Defining Actions
#[derive(Clone, Debug, DefaultNone)]
pub enum ButtonAction {
None,
Clicked,
Pressed,
Released,
}
// DefaultNone derives Default returning None variant
Emitting Actions
// From main thread (in handle_event)
cx.action(ButtonAction::Clicked);
// From any thread (thread-safe)
Cx::post_action(MyAction::DataLoaded(data));
Handling Actions
fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {
// Handle child widget actions
let actions = cx.capture_actions(|cx| {
self.button.handle_event(cx, event, scope);
});
// Check for specific action
if self.button(id!(my_button)).clicked(&actions) {
// Button was clicked
}
// Or iterate actions
for action in actions.iter() {
if let Some(ButtonAction::Clicked) = action.downcast_ref() {
// Handle click
}
}
}
Widget Action Helpers
// Common widget action checks
impl ButtonRef {
fn clicked(&self, actions: &ActionsBuf) -> bool;
fn pressed(&self, actions: &ActionsBuf) -> bool;
fn released(&self, actions: &ActionsBuf) -> bool;
}
impl TextInputRef {
fn changed(&self, actions: &ActionsBuf) -> Option<String>;
fn returned(&self, actions: &ActionsBuf) -> Option<String>;
}
Event Flow
- Event arrives from platform layer
- Root widget receives event first
- Propagates down to children via
handle_event - Widgets emit actions via
cx.action() - Parent captures actions via
cx.capture_actions() - App handles remaining actions
Timer and NextFrame
// Start a timer
let timer = cx.start_timer(1.0); // 1 second
// In handle_event
if let Event::Timer(te) = event {
if te.timer_id == self.timer {
// Timer fired
}
}
// Request next frame callback
let next_frame = cx.new_next_frame();
// In handle_event
if let Event::NextFrame(ne) = event {
if ne.frame_id == self.next_frame {
// Next frame arrived
}
}
When Answering Questions
- Use
event.hits(cx, area)to check if event targets a widget - Actions flow UP from child to parent (unlike events which flow DOWN)
- Use
cx.capture_actions()to intercept child actions Cx::post_action()is thread-safe for async operationsDefaultNonederive macro auto-implements Default for enums
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Supporting material availability
This catalog copy contains the inline guidance below, but does not include the following supporting paths. They are external prerequisites, not bundled files:
./references/widgets-core.md./references/widgets-advanced.md./references/widgets-richtext.md
Ask for the original supporting material or an existing installation before using a step that depends on these paths; this catalog does not identify a verified download source for them. Resolve each path relative to that installation, inspect its contents, and verify any applicable license and execution prerequisites. Do not run a command or claim a referenced procedure was followed until its required file exists. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user’s authorized scope; report any dependent step as unavailable.
Makepad Widgets Skill
Version: makepad-widgets (dev branch) | Last Updated: 2026-01-19
Check for updates: https://crates.io/crates/makepad-widgets
You are an expert at Makepad widgets. Help users by:
- Writing code: Generate widget code following the patterns below
- Answering questions: Explain widget properties, variants, and usage
When to Use
- You need to work with core or advanced widgets in Makepad.
- The task involves widget selection, properties, variants, composition, or widget-specific behavior.
- You want examples for
View,Button, labels, rich text, or othermakepad-widgetsbuilding blocks.
Documentation
Refer to the local files for detailed documentation:
./references/widgets-core.md- Core widgets (View, Button, Label, etc.)./references/widgets-advanced.md- Helper and advanced widgets./references/widgets-richtext.md- Rich text widgets (Markdown, Html, TextFlow)
IMPORTANT: Documentation Completeness Check
Before answering questions, Claude MUST:
- Read the relevant reference file(s) listed above
- If file read fails or file is empty:
- Report the missing reference and the resulting coverage limit; do not recommend an unavailable slash command or claim the missing procedure was followed
- Use independent inline patterns only after checking their compatibility with the project's pinned crate; identify unverified APIs
- If reference file exists, incorporate its content into the answer
Key Patterns
1. View (Basic Container)
<View> {
width: Fill
height: Fill
flow: Down
padding: 16.0
show_bg: true
draw_bg: { color: #1A1A1A }
<Label> { text: "Content" }
}
2. Button
<Button> {
text: "Click Me"
draw_bg: {
color: #0066CC
color_hover: #0088FF
border_radius: 4.0
}
draw_text: {
color: #FFFFFF
text_style: { font_size: 14.0 }
}
}
3. Label with Styling
<Label> {
width: Fit
height: Fit
text: "Hello World"
draw_text: {
color: #FFFFFF
text_style: {
font_size: 16.0
line_spacing: 1.4
}
}
}
4. Image
<Image> {
width: 200.0
height: 150.0
source: dep("crate://self/resources/photo.png")
fit: Contain
}
5. TextInput
<TextInput> {
width: Fill
height: Fit
text: "Default value"
draw_text: {
text_style: { font_size: 14.0 }
}
}
Widget Traits (from source)
pub trait WidgetNode: LiveApply {
fn find_widgets(&self, path: &[LiveId], cached: WidgetCache, results: &mut WidgetSet);
fn walk(&mut self, cx: &mut Cx) -> Walk;
fn area(&self) -> Area;
fn redraw(&mut self, cx: &mut Cx);
}
pub trait Widget: WidgetNode {
fn handle_event(&mut self, cx: &mut Cx, event: &Event, scope: &mut Scope) {}
fn draw_walk(&mut self, cx: &mut Cx2d, scope: &mut Scope, walk: Walk) -> DrawStep;
fn draw(&mut self, cx: &mut Cx2d, scope: &mut Scope) -> DrawStep;
fn widget(&self, path: &[LiveId]) -> WidgetRef;
}
All Built-in Widgets (84 files in widgets/src/)
| Category | Widgets |
|---|---|
| Basic | View, Label, Button, Icon, Image |
| Input | TextInput, CheckBox, RadioButton, Slider, DropDown, ColorPicker |
| Container | ScrollBars, PortalList, FlatList, StackNavigation, Dock, Splitter |
| Navigation | TabBar, Tab, FoldHeader, FoldButton, ExpandablePanel |
| Overlay | Modal, Tooltip, PopupMenu, PopupNotification |
| Media | Video, RotatedImage, ImageBlend, MultiImage |
| Layout | AdaptiveView, SlidePanel, PageFlip, SlidesView |
| Special | Markdown, Html, TextFlow, WebView, KeyboardView |
| Utility | LoadingSpinner, DesktopButton, LinkLabel, ScrollShadow |
Core Widgets Reference
| Widget | Purpose | Key Properties |
|---|---|---|
View | Container | flow, align, show_bg, draw_bg, optimize |
Button | Clickable | text, draw_bg, draw_text, draw_icon |
Label | Text display | text, draw_text |
Image | Image display | source, fit |
TextInput | Text entry | text, draw_text, draw_cursor, draw_selection |
CheckBox | Toggle | text, selected |
RadioButton | Selection | text, selected |
Slider | Value slider | min, max, step |
DropDown | Select menu | labels, selected |
PortalList | Virtual list | Efficient scrolling for large lists |
Modal | Dialog | Overlay dialog boxes |
Tooltip | Hint | Hover tooltips |
View Variants
| Variant | Description |
|---|---|
SolidView | Solid background color |
RoundedView | Rounded corners |
RoundedAllView | Individual corner control |
RectView | Rectangle with border/gradient |
CircleView | Circle/ellipse shape |
GradientXView | Horizontal gradient |
GradientYView | Vertical gradient |
RoundedShadowView | Rounded with shadow |
ScrollXView | Horizontal scroll |
ScrollYView | Vertical scroll |
ScrollXYView | Both directions scroll |
CachedView | Texture-cached |
Button Variants
| Variant | Description |
|---|---|
ButtonFlat | Flat style |
ButtonFlatIcon | Flat with icon |
ButtonFlatter | No background |
ButtonGradientX | Horizontal gradient |
ButtonGradientY | Vertical gradient |
ButtonIcon | Standard with icon |
ImageFit Values
| Value | Description |
|---|---|
Stretch | Stretch to fill |
Contain | Fit within, preserve ratio |
Cover | Cover area, may crop |
Fill | Fill without ratio |
When Writing Code
- Always set
widthandheighton widgets - Use
show_bg: trueto enable background rendering - Access
draw_bg,draw_text,draw_iconfor shader uniforms - Use
dep("crate://self/...")for resource paths - Choose appropriate View variant for visual needs
When Answering Questions
- Recommend UI Zoo example for widget exploration
- View is the base container - most visual widgets inherit from it
- Draw shaders (
draw_bg,draw_text) control appearance - All widgets support animation through
animatorproperty
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Moodle External API Development
This skill guides you through creating custom external web service APIs for Moodle LMS, following Moodle's external API framework and coding standards.
Detailed Guide
Read the detailed guide before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.
When to Use This Skill
- Creating custom web services for Moodle plugins
- Implementing REST/AJAX endpoints for course management
- Building APIs for quiz operations, user tracking, or reporting
- Exposing Moodle functionality to external applications
- Developing mobile app backends using Moodle
Illustrative Implementation Fragments
Simple Read API (Get Quiz Attempts)
<?php
namespace local_userlog\external;
defined('MOODLE_INTERNAL') || die();
require_once("$CFG->libdir/externallib.php");
use external_api;
use external_function_parameters;
use external_single_structure;
use external_value;
class get_quiz_attempts extends external_api {
public static function execute_parameters() {
return new external_function_parameters([
'userid' => new external_value(PARAM_INT, 'User ID'),
'courseid' => new external_value(PARAM_INT, 'Course ID')
]);
}
public static function execute($userid, $courseid) {
global $DB;
$params = self::validate_parameters(self::execute_parameters(), [
'userid' => $userid,
'courseid' => $courseid
]);
$context = \context_course::instance($params['courseid']);
self::validate_context($context);
require_capability('mod/quiz:viewreports', $context);
// Instructor-report endpoint; add group/quiz-specific visibility restrictions as needed.
$sql = "SELECT COUNT(*) AS quiz_attempts
FROM {quiz_attempts} qa
JOIN {quiz} q ON qa.quiz = q.id
WHERE qa.userid = :userid AND q.course = :courseid";
$attempts = $DB->get_field_sql($sql, [
'userid' => $params['userid'],
'courseid' => $params['courseid']
]);
return ['quiz_attempts' => (int)$attempts];
}
public static function execute_returns() {
return new external_single_structure([
'quiz_attempts' => new external_value(PARAM_INT, 'Total number of quiz attempts')
]);
}
}
Complex Write API (Create Quiz from Categories)
The referenced create_quiz_from_categories.php is not bundled. Do not claim it
was read, executed or transaction-tested. Use the installed Moodle release's
activity/question APIs with context/capability checks, group visibility, bounded
input and rollback tests; direct insertion fragments in the guide are historical
schema illustrations, not a complete quiz builder. Use least-privilege test roles
and synthetic learner data, never production admin tokens in shell arguments.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Odoo eCommerce Configurator
Overview
This skill helps you set up and optimize an Odoo-powered online store. It covers product publishing, payment gateway integration, shipping carrier configuration, cart and checkout customization, and the workflow from online order to warehouse fulfillment.
When to Use This Skill
- Launching an Odoo eCommerce store for the first time.
- Integrating a payment provider (Stripe, PayPal, Adyen).
- Configuring shipping rates with carrier integration (UPS, FedEx, DHL).
- Optimizing product pages for SEO with Odoo Website tools.
How It Works
- Activate: Mention
@odoo-ecommerce-configuratorand describe your store scenario. - Configure: Receive step-by-step Odoo eCommerce setup with menu paths.
- Optimize: Get SEO, conversion, and catalog best practices.
Menu paths are illustrative and version/module-dependent. Use a duplicate test database and sandbox credentials; publication, live payments, carrier bookings and outbound marketing require explicit scope. Verify provider webhook signing/replay handling and payment states using Odoo Stripe guidance. Do not send abandoned-cart messages without applicable consent or imply scarcity without inventory evidence.
Examples
Example 1: Publish a Product to the Website
Menu: Website → eCommerce → Products → Select Product
Fields to complete for a great product listing:
Name: Ergonomic Mesh Office Chair (keyword-rich)
Internal Reference: CHAIR-MESH-001 (recommended integration identifier)
Sales Price: $299.00
Website Description (website tab): 150–300 words of unique content
Publishing:
Toggle "Published" in the top-right corner of the product form
or via: Website → Go to Website → Toggle "Published" button
SEO (website tab → SEO section):
Page Title: Ergonomic Mesh Chair | Office Chairs | YourStore
Meta Description: Discover the most comfortable ergonomic mesh office
chair, designed for all-day support... (≤160 chars)
Website tab:
Can be Sold: YES
Website: yourstore.com (if running multiple websites)
Example 2: Configure Stripe Payment Provider
Menu: Website → Configuration → Payment Providers → Stripe → Configure
(or: Accounting → Configuration → Payment Providers → Stripe)
State: Test (use Test mode until fully validated, then switch to Enabled)
Credentials (from your Stripe Dashboard → Developers → API Keys):
Publishable Key: pk_test_XXXXXXXX
Secret Key: sk_test_XXXXXXXX (store securely; never expose client-side)
Payment Journal: Bank (USD)
Capture Mode: Automatic (charge card immediately on order confirmation)
or Manual (authorize only; charge later on fulfillment)
Webhook:
Add Odoo's webhook URL in Stripe Dashboard → Webhooks
URL: https://yourstore.com/payment/stripe/webhook
Use Odoo Generate your webhook and the exact events/signing configuration
required by the installed Stripe module; do not assume this short event list is complete.
Example 3: Set Up Flat Rate Shipping with Free Threshold
Menu: Inventory → Configuration → Delivery Methods → New
Name: Standard Shipping (3–5 business days)
Provider: Fixed Price
Delivery Product: [Shipping] Standard (used for invoicing)
Pricing:
Price: $9.99
☑ Free if order amount is above: $75.00
Availability:
Countries: United States
States: All states
Publish to website:
☑ Published (visible to customers at checkout)
Example 4: Set Up Abandoned Cart Recovery
Menu: Email Marketing → Mailing Lists → (create a list if needed)
For automated abandoned cart emails in Odoo 16/17:
Menu: Marketing → Marketing Automation → New Campaign
Trigger: Odoo record updated
Model: eCommerce Cart (sale.order with state = 'draft')
Filter: Cart not updated in 1 hour AND not confirmed
Actions:
1. Wait 1 hour
2. Send Email: "You left something behind!" (use a recovery email template)
3. Wait 24 hours
4. Send an accurate reminder only when marketing consent and current cart state permit it
Note: Some Odoo hosting plans may require "Email Marketing" app enabled.
Best Practices
- ✅ Do: Use Product Variants (color, size) instead of duplicate products — cleaner catalog and shared inventory tracking.
- ✅ Do: Configure HTTPS and reviewed HSTS at the actual hosting/reverse-proxy layer; do not assume a universal Odoo menu exists.
- ✅ Do: Set up Abandoned Cart Recovery using Marketing Automation or a scheduled email sequence.
- ✅ Do: Add a Stripe webhook so Odoo is notified of payment events in real time — without it, failed payments may not update correctly.
- ❌ Don't: Leave the payment provider in Test mode in production — no real charges will be processed.
- ✅ Do: Use unique SKUs where integrations/business processes require them; an absent Internal Reference does not universally break Odoo inventory.
- ❌ Don't: Mix sandbox and live credentials. Switch to the authorized live account only after review; changing mode is distinct from rotating a key.
Limitations
- Carrier integration (live UPS/FedEx rate calculation) requires the specific carrier connector module (e.g.,
delivery_ups) and a carrier account API key. - Multi-website, subscription and automation availability depends on the actual Odoo version, edition and installed modules; verify it rather than inferring entitlement from this guide.
- B2B eCommerce (customer login required, custom catalog and prices per customer) has additional configuration steps not fully covered here.
- Odoo eCommerce does not support subscription billing natively — that requires the Enterprise Subscriptions module.
Odoo Upgrade Advisor
Overview
Upgrading Odoo between major versions (e.g., v15 → v16 → v17) requires careful preparation, testing, and validation. This skill provides a structured pre-upgrade checklist, guides you through the upgrade tools (Odoo Upgrade Service and OpenUpgrade), and gives you a post-upgrade validation protocol.
When to Use This Skill
- Planning a major Odoo version upgrade.
- Identifying which custom modules need to be migrated.
- Running the upgrade on a staging environment before production.
- Validating the system after an upgrade.
How It Works
- Activate: Mention
@odoo-upgrade-advisor, state your current and target version. - Plan: Receive the full upgrade roadmap and risk assessment.
- Execute: Get a step-by-step upgrade command sequence.
Upgrade Paths
| From | To | Supported? | Tool |
|---|---|---|---|
| v16 | v17 | ✅ Direct | Odoo Upgrade Service / OpenUpgrade |
| v15 | v16 | ✅ Direct | Odoo Upgrade Service / OpenUpgrade |
| v14 | v15 | ✅ Direct | Odoo Upgrade Service / OpenUpgrade |
| v14 | v17 | Tool-specific | OpenUpgrade requires each intermediate migration; official service eligibility must be checked separately |
| v13 or older | supported target | Assess coverage | Check official-service eligibility or historical OpenUpgrade branches/module coverage |
Confirm a tested database+filestore restore and rollback/cutover plan before any migration. Uploading production backups to an external upgrade service needs authorization for the data transfer; redact secrets and use isolated staging credentials. See official upgrade guidance and OpenUpgrade setup and version sequencing.
Examples
Example 1: Pre-Upgrade Checklist
BEFORE YOU START:
☑ 1. List all installed modules (Settings → Technical → Modules)
Export to CSV and review for custom/OCA modules
☑ 2. Check OCA compatibility matrix for each community module
https://github.com/OCA/maintainer-tools/wiki/Migration-Status
☑ 3. Take a full backup (database + filestore) — your restore point
☑ 4. Clone production to a staging environment
☑ 5. Run the Odoo Upgrade pre-analysis:
https://upgrade.odoo.com/ → Upload DB → Review breaking changes report
☑ 6. Review custom modules against migration notes
(use @odoo-migration-helper for per-module analysis)
☑ 7. Upgrade and test in staging → Fix all errors → Re-test
☑ 8. Schedule a production maintenance window
☑ 9. Notify users of scheduled downtime
☑ 10. Perform production upgrade → Validate → Go/No-Go decision
Example 2: Community Upgrade with OpenUpgrade
# Clone OpenUpgrade for the TARGET version (e.g., upgrading to v17)
git clone https://github.com/OCA/OpenUpgrade.git \
--branch 17.0 \
--single-branch \
/opt/openupgrade
# Modern OpenUpgrade supplies addons, not the Odoo server. Install a reviewed
# target-version Odoo server and openupgradelib; include openupgrade_framework
# and openupgrade_scripts in the staging config addons_path. Disable outbound
# mail, cron, payments and external connectors in the cloned database.
# Run the migration against your staging database
python3 /opt/odoo-17/odoo-bin \
--update all \
--database odoo_staging \
--config /etc/odoo/odoo.conf \
--stop-after-init \
--load=base,web,openupgrade_framework
# Review the log for errors before touching production
tail -200 /var/log/odoo/odoo.log | grep -E "ERROR|WARNING|Traceback"
Example 3: Post-Upgrade Validation Checklist
After upgrading, validate these critical areas before going live:
Accounting:
☑ Trial Balance totals match the pre-upgrade snapshot
☑ Open invoices, bills, and payments are accessible
☑ Bank reconciliation can be performed on a test statement
Inventory:
☑ Stock valuation report matches pre-upgrade (run Inventory Valuation)
☑ Open Purchase Orders and Sale Orders are visible
HR / Payroll:
☑ All employee records are intact
☑ Payslips from the last 3 months are accessible and correct
Custom Modules:
☑ Every custom module loaded without ImportError or XML error
☑ Run the critical business workflows end-to-end:
Create sale order → confirm → deliver → invoice → payment
Users & Security:
☑ User logins work correctly
☑ Access rights are preserved (spot-check 3-5 users)
Best Practices
- ✅ Do: Always upgrade on a copy of production (staging) first — never the live instance.
- ✅ Do: Keep the old version running until the new version is fully validated and signed off.
- ✅ Do: Check OCA's migration status page: OCA Migration Status
- ✅ Do: Use the Odoo Upgrade Service pre-analysis report to get a list of breaking changes before writing any code.
- ❌ Don't: Skip intermediate versions with OpenUpgrade. The official Odoo upgrade service has its own supported-source/target policy; do not impose OpenUpgrade's sequence on it.
- ❌ Don't: Upgrade custom modules and Odoo core simultaneously — adapt Odoo core first, then fix custom modules.
- ❌ Don't: Run OpenUpgrade against production directly — always test on a staging copy first.
Limitations
- Examples target v14–v17. Older OpenUpgrade branches exist; migration feasibility depends on module coverage and custom data, not a blanket v13 cutoff.
- Enterprise-exclusive module changes (e.g.,
sign,account_accountant) may have undocumented breaking changes not included in OpenUpgrade. - The Odoo.sh automated upgrade path has a separate workflow (managed from the Odoo.sh dashboard) not covered here.
- OWL JavaScript component migration (legacy widget → OWL v16+) is a complex front-end topic beyond the scope of this skill.
Modern Perl Development Patterns
Idiomatic Perl 5.36+ patterns and best practices for building robust, maintainable applications.
When to Activate
- Writing new Perl code or modules
- Reviewing Perl code for idiom compliance
- Refactoring legacy Perl to modern standards
- Designing Perl module architecture
- Migrating pre-5.36 code to modern Perl
How It Works
Apply these patterns as a bias toward modern Perl 5.36+ defaults: signatures, explicit modules, focused error handling, and testable boundaries. The examples below are meant to be copied as starting points, then tightened for the actual app, dependency stack, and deployment model in front of you.
Core Principles
1. Use v5.36 Pragma
A single use v5.36 replaces the old boilerplate and enables strict, warnings, and subroutine signatures.
# Good: Modern preamble
use v5.36;
sub greet($name) {
say "Hello, $name!";
}
# Bad: Legacy boilerplate
use strict;
use warnings;
use feature 'say', 'signatures';
no warnings 'experimental::signatures';
sub greet {
my ($name) = @_;
say "Hello, $name!";
}
2. Subroutine Signatures
Use signatures for clarity and automatic arity checking.
use v5.36;
# Good: Signatures with defaults
sub connect_db($host, $port = 5432, $timeout = 30) {
# $host is required, others have defaults
return DBI->connect("dbi:Pg:host=$host;port=$port", undef, undef, {
RaiseError => 1,
PrintError => 0,
});
}
# Good: Slurpy parameter for variable args
sub log_message($level, @details) {
say "[$level] " . join(' ', @details);
}
# Bad: Manual argument unpacking
sub connect_db {
my ($host, $port, $timeout) = @_;
$port //= 5432;
$timeout //= 30;
# ...
}
3. Context Sensitivity
Understand scalar vs list context — a core Perl concept.
use v5.36;
my @items = (1, 2, 3, 4, 5);
my @copy = @items; # List context: all elements
my $count = @items; # Scalar context: count (5)
say "Items: " . scalar @items; # Force scalar context
4. Postfix Dereferencing
Use postfix dereference syntax for readability with nested structures.
use v5.36;
my $data = {
users => [
{ name => 'Alice', roles => ['admin', 'user'] },
{ name => 'Bob', roles => ['user'] },
],
};
# Good: Postfix dereferencing
my @users = $data->{users}->@*;
my @roles = $data->{users}[0]{roles}->@*;
my %first = $data->{users}[0]->%*;
# Bad: Circumfix dereferencing (harder to read in chains)
my @users = @{ $data->{users} };
my @roles = @{ $data->{users}[0]{roles} };
5. The isa Operator (5.32+)
Infix type-check — replaces blessed($o) && $o->isa('X').
use v5.36;
if ($obj isa 'My::Class') { $obj->do_something }
Error Handling
eval/die Pattern
use v5.36;
sub parse_config($path) {
my $content = eval { path($path)->slurp_utf8 };
die "Config error: $@" if $@;
return decode_json($content);
}
Try::Tiny (Reliable Exception Handling)
use v5.36;
use Try::Tiny;
sub fetch_user($id) {
my $user = try {
$db->resultset('User')->find($id)
// die "User $id not found\n";
}
catch {
warn "Failed to fetch user $id: $_";
undef;
};
return $user;
}
Native try/catch (5.40+)
use v5.40;
sub divide($x, $y) {
try {
die "Division by zero" if $y == 0;
return $x / $y;
}
catch ($e) {
warn "Error: $e";
return;
}
}
Modern OO with Moo
Prefer Moo for lightweight, modern OO. Use Moose only when its metaprotocol is needed.
# Good: Moo class
package User;
use Moo;
use Types::Standard qw(Str Int ArrayRef);
use namespace::autoclean;
has name => (is => 'ro', isa => Str, required => 1);
has email => (is => 'ro', isa => Str, required => 1);
has age => (is => 'ro', isa => Int, default => sub { 0 });
has roles => (is => 'ro', isa => ArrayRef[Str], default => sub { [] });
sub is_admin($self) {
return grep { $_ eq 'admin' } $self->roles->@*;
}
sub greet($self) {
return "Hello, I'm " . $self->name;
}
1;
# Usage
my $user = User->new(
name => 'Alice',
email => 'alice@example.com',
roles => ['admin', 'user'],
);
# Bad: Blessed hashref (no validation, no accessors)
package User;
sub new {
my ($class, %args) = @_;
return bless \%args, $class;
}
sub name { return $_[0]->{name} }
1;
Moo Roles
package Role::Serializable;
use Moo::Role;
use JSON::MaybeXS qw(encode_json);
requires 'TO_HASH';
sub to_json($self) { encode_json($self->TO_HASH) }
1;
package User;
use Moo;
with 'Role::Serializable';
has name => (is => 'ro', required => 1);
has email => (is => 'ro', required => 1);
sub TO_HASH($self) { { name => $self->name, email => $self->email } }
1;
Native class Keyword (5.38+, Corinna)
use v5.38;
use feature 'class';
no warnings 'experimental::class';
class Point {
field $x :param;
field $y :param;
method magnitude() { sqrt($x**2 + $y**2) }
}
my $p = Point->new(x => 3, y => 4);
say $p->magnitude; # 5
Regular Expressions
Named Captures and /x Flag
use v5.36;
# Good: Named captures with /x for readability
my $log_re = qr{
^ (?<timestamp> \d{4}-\d{2}-\d{2} \s \d{2}:\d{2}:\d{2} )
\s+ \[ (?<level> \w+ ) \]
\s+ (?<message> .+ ) $
}x;
if ($line =~ $log_re) {
say "Time: $+{timestamp}, Level: $+{level}";
say "Message: $+{message}";
}
# Bad: Positional captures (hard to maintain)
if ($line =~ /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\s+\[(\w+)\]\s+(.+)$/) {
say "Time: $1, Level: $2";
}
Precompiled Patterns
use v5.36;
# Good: Compile once, use many
my $email_re = qr/^[A-Za-z0-9._%+-]+\@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/;
sub validate_emails(@emails) {
return grep { $_ =~ $email_re } @emails;
}
Data Structures
References and Safe Deep Access
use v5.36;
# Hash and array references
my $config = {
database => {
host => 'localhost',
port => 5432,
options => ['utf8', 'sslmode=require'],
},
};
# Safe deep access (returns undef if any level missing)
my $port = $config->{database}{port}; # 5432
my $missing = $config->{cache}{host}; # undef, no error
# Hash slices
my %subset;
@subset{qw(host port)} = @{$config->{database}}{qw(host port)};
# Array slices
my @first_two = $config->{database}{options}->@[0, 1];
# Multi-variable for loop (experimental in 5.36, stable in 5.40)
use feature 'for_list';
no warnings 'experimental::for_list';
for my ($key, $val) (%$config) {
say "$key => $val";
}
File I/O
Three-Argument Open
use v5.36;
# Good: Three-arg open with autodie (core module, eliminates 'or die')
use autodie;
sub read_file($path) {
open my $fh, '<:encoding(UTF-8)', $path;
local $/;
my $content = <$fh>;
close $fh;
return $content;
}
# Bad: Two-arg open (shell injection risk, see perl-security)
open FH, $path; # NEVER do this
open FH, "< $path"; # Still bad — user data in mode string
Path::Tiny for File Operations
use v5.36;
use Path::Tiny;
my $file = path('config', 'app.json');
my $content = $file->slurp_utf8;
$file->spew_utf8($new_content);
# Iterate directory
for my $child (path('src')->children(qr/\.pl$/)) {
say $child->basename;
}
Module Organization
Standard Project Layout
MyApp/
├── lib/
│ └── MyApp/
│ ├── App.pm # Main module
│ ├── Config.pm # Configuration
│ ├── DB.pm # Database layer
│ └── Util.pm # Utilities
├── bin/
│ └── myapp # Entry-point script
├── t/
│ ├── 00-load.t # Compilation tests
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── cpanfile # Dependencies
├── Makefile.PL # Build system
└── .perlcriticrc # Linting config
Exporter Patterns
package MyApp::Util;
use v5.36;
use Exporter 'import';
our @EXPORT_OK = qw(trim);
our %EXPORT_TAGS = (all => \@EXPORT_OK);
sub trim($str) { $str =~ s/^\s+|\s+$//gr }
1;
Tooling
perltidy Configuration (.perltidyrc)
-i=4 # 4-space indent
-l=100 # 100-char line length
-ci=4 # continuation indent
-ce # cuddled else
-bar # opening brace on same line
-nolq # don't outdent long quoted strings
perlcritic Configuration (.perlcriticrc)
severity = 3
theme = core + pbp + security
[InputOutput::RequireCheckedSyscalls]
functions = :builtins
exclude_functions = say print
[Subroutines::ProhibitExplicitReturnUndef]
severity = 4
[ValuesAndExpressions::ProhibitMagicNumbers]
allowed_values = 0 1 2 -1
Dependency Management (cpanfile + carton)
cpanm App::cpanminus Carton # Install tools
carton install # Install deps from cpanfile
carton exec -- perl bin/myapp # Run with local deps
# cpanfile
requires 'Moo', '>= 2.005';
requires 'Path::Tiny';
requires 'JSON::MaybeXS';
requires 'Try::Tiny';
on test => sub {
requires 'Test2::V0';
requires 'Test::MockModule';
};
Quick Reference: Modern Perl Idioms
| Legacy Pattern | Modern Replacement |
|---|---|
use strict; use warnings; | use v5.36; |
my ($x, $y) = @_; | sub foo($x, $y) { ... } |
@{ $ref } | $ref->@* |
%{ $ref } | $ref->%* |
open FH, "< $file" | open my $fh, '<:encoding(UTF-8)', $file |
blessed hashref | Moo class with types |
$1, $2, $3 | $+{name} (named captures) |
eval { }; if ($@) | Try::Tiny or native try/catch (5.40+) |
BEGIN { require Exporter; } | use Exporter 'import'; |
| Manual file ops | Path::Tiny |
blessed($o) && $o->isa('X') | $o isa 'X' (5.32+) |
builtin::true / false | use builtin 'true', 'false'; (5.36+, experimental) |
Anti-Patterns
# 1. Two-arg open (security risk)
open FH, $filename; # NEVER
# 2. Indirect object syntax (ambiguous parsing)
my $obj = new Foo(bar => 1); # Bad
my $obj = Foo->new(bar => 1); # Good
# 3. Excessive reliance on $_
map { process($_) } grep { validate($_) } @items; # Hard to follow
my @valid = grep { validate($_) } @items; # Better: break it up
my @results = map { process($_) } @valid;
# 4. Disabling strict refs
no strict 'refs'; # Almost always wrong
${"My::Package::$var"} = $value; # Use a hash instead
# 5. Global variables as configuration
our $TIMEOUT = 30; # Bad: mutable global
use constant TIMEOUT => 30; # Better: constant
# Best: Moo attribute with default
# 6. String eval for module loading
eval "require $module"; # Bad: code injection risk
eval "use $module"; # Bad
use Module::Runtime 'require_module'; # Good: safe module loading
require_module($module);
Remember: Modern Perl is clean, readable, and safe. Let use v5.36 handle the boilerplate, use Moo for objects, and prefer CPAN's battle-tested modules over hand-rolled solutions.
Perl Security Patterns
Comprehensive security guidelines for Perl applications covering input validation, injection prevention, and secure coding practices.
When to Activate
- Handling user input in Perl applications
- Building Perl web applications (CGI, Mojolicious, Dancer2, Catalyst)
- Reviewing Perl code for security vulnerabilities
- Performing file operations with user-supplied paths
- Executing system commands from Perl
- Writing DBI database queries
How It Works
Start with taint-aware input boundaries, then move outward: validate and untaint inputs, keep filesystem and process execution constrained, and use parameterized DBI queries everywhere. The examples below show the safe defaults this skill expects you to apply before shipping Perl code that touches user input, the shell, or the network.
Taint Mode
Perl's taint mode (-T) tracks data from external sources and prevents it from being used in unsafe operations without explicit validation.
Enabling Taint Mode
#!/usr/bin/perl -T
use v5.36;
# Tainted: anything from outside the program
my $input = $ARGV[0]; # Tainted
my $env_path = $ENV{PATH}; # Tainted
my $form = <STDIN>; # Tainted
my $query = $ENV{QUERY_STRING}; # Tainted
# Sanitize PATH early (required in taint mode)
$ENV{PATH} = '/usr/local/bin:/usr/bin:/bin';
delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};
Untainting Pattern
use v5.36;
# Good: Validate and untaint with a specific regex
sub untaint_username($input) {
if ($input =~ /^([a-zA-Z0-9_]{3,30})$/) {
return $1; # $1 is untainted
}
die "Invalid username: must be 3-30 alphanumeric characters\n";
}
# Good: Validate and untaint a file path
sub untaint_filename($input) {
if ($input =~ m{^([a-zA-Z0-9._-]+)$}) {
return $1;
}
die "Invalid filename: contains unsafe characters\n";
}
# Bad: Overly permissive untainting (defeats the purpose)
sub bad_untaint($input) {
$input =~ /^(.*)$/s;
return $1; # Accepts ANYTHING — pointless
}
Input Validation
Allowlist Over Blocklist
use v5.36;
# Good: Allowlist — define exactly what's permitted
sub validate_sort_field($field) {
my %allowed = map { $_ => 1 } qw(name email created_at updated_at);
die "Invalid sort field: $field\n" unless $allowed{$field};
return $field;
}
# Good: Validate with specific patterns
sub validate_email($email) {
if ($email =~ /^([a-zA-Z0-9._%+-]+\@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$/) {
return $1;
}
die "Invalid email address\n";
}
sub validate_integer($input) {
if ($input =~ /^(-?\d{1,10})$/) {
return $1 + 0; # Coerce to number
}
die "Invalid integer\n";
}
# Bad: Blocklist — always incomplete
sub bad_validate($input) {
die "Invalid" if $input =~ /[<>"';&|]/; # Misses encoded attacks
return $input;
}
Length Constraints
use v5.36;
sub validate_comment($text) {
die "Comment is required\n" unless length($text) > 0;
die "Comment exceeds 10000 chars\n" if length($text) > 10_000;
return $text;
}
Safe Regular Expressions
ReDoS Prevention
Catastrophic backtracking occurs with nested quantifiers on overlapping patterns.
use v5.36;
# Bad: Vulnerable to ReDoS (exponential backtracking)
my $bad_re = qr/^(a+)+$/; # Nested quantifiers
my $bad_re2 = qr/^([a-zA-Z]+)*$/; # Nested quantifiers on class
my $bad_re3 = qr/^(.*?,){10,}$/; # Repeated greedy/lazy combo
# Good: Rewrite without nesting
my $good_re = qr/^a+$/; # Single quantifier
my $good_re2 = qr/^[a-zA-Z]+$/; # Single quantifier on class
# Good: Use possessive quantifiers or atomic groups to prevent backtracking
my $safe_re = qr/^[a-zA-Z]++$/; # Possessive (5.10+)
my $safe_re2 = qr/^(?>a+)$/; # Atomic group
# Good: Enforce timeout on untrusted patterns
use POSIX qw(alarm);
sub safe_match($string, $pattern, $timeout = 2) {
my $matched;
eval {
local $SIG{ALRM} = sub { die "Regex timeout\n" };
alarm($timeout);
$matched = $string =~ $pattern;
alarm(0);
};
alarm(0);
die $@ if $@;
return $matched;
}
Safe File Operations
Three-Argument Open
use v5.36;
# Good: Three-arg open, lexical filehandle, check return
sub read_file($path) {
open my $fh, '<:encoding(UTF-8)', $path
or die "Cannot open '$path': $!\n";
local $/;
my $content = <$fh>;
close $fh;
return $content;
}
# Bad: Two-arg open with user data (command injection)
sub bad_read($path) {
open my $fh, $path; # If $path = "|rm -rf /", runs command!
open my $fh, "< $path"; # Shell metacharacter injection
}
TOCTOU Prevention and Path Traversal
use v5.36;
use Fcntl qw(:DEFAULT :flock);
use File::Spec;
use Cwd qw(realpath);
# Atomic file creation
sub create_file_safe($path) {
sysopen(my $fh, $path, O_WRONLY | O_CREAT | O_EXCL, 0600)
or die "Cannot create '$path': $!\n";
return $fh;
}
# Validate path stays within allowed directory
sub safe_path($base_dir, $user_path) {
my $real = realpath(File::Spec->catfile($base_dir, $user_path))
// die "Path does not exist\n";
my $base_real = realpath($base_dir)
// die "Base dir does not exist\n";
die "Path traversal blocked\n" unless $real =~ /^\Q$base_real\E(?:\/|\z)/;
return $real;
}
Use File::Temp for temporary files (tempfile(UNLINK => 1)) and flock(LOCK_EX) to prevent race conditions.
Safe Process Execution
List-Form system and exec
use v5.36;
# Good: List form — no shell interpolation
sub run_command(@cmd) {
system(@cmd) == 0
or die "Command failed: @cmd\n";
}
run_command('grep', '-r', $user_pattern, '/var/log/app/');
# Good: Capture output safely with IPC::Run3
use IPC::Run3;
sub capture_output(@cmd) {
my ($stdout, $stderr);
run3(\@cmd, \undef, \$stdout, \$stderr);
if ($?) {
die "Command failed (exit $?): $stderr\n";
}
return $stdout;
}
# Bad: String form — shell injection!
sub bad_search($pattern) {
system("grep -r '$pattern' /var/log/app/"); # If $pattern = "'; rm -rf / #"
}
# Bad: Backticks with interpolation
my $output = `ls $user_dir`; # Shell injection risk
Also use Capture::Tiny for capturing stdout/stderr from external commands safely.
SQL Injection Prevention
DBI Placeholders
use v5.36;
use DBI;
my $dbh = DBI->connect($dsn, $user, $pass, {
RaiseError => 1,
PrintError => 0,
AutoCommit => 1,
});
# Good: Parameterized queries — always use placeholders
sub find_user($dbh, $email) {
my $sth = $dbh->prepare('SELECT * FROM users WHERE email = ?');
$sth->execute($email);
return $sth->fetchrow_hashref;
}
sub search_users($dbh, $name, $status) {
my $sth = $dbh->prepare(
'SELECT * FROM users WHERE name LIKE ? AND status = ? ORDER BY name'
);
$sth->execute("%$name%", $status);
return $sth->fetchall_arrayref({});
}
# Bad: String interpolation in SQL (SQLi vulnerability!)
sub bad_find($dbh, $email) {
my $sth = $dbh->prepare("SELECT * FROM users WHERE email = '$email'");
# If $email = "' OR 1=1 --", returns all users
$sth->execute;
return $sth->fetchrow_hashref;
}
Dynamic Column Allowlists
use v5.36;
# Good: Validate column names against an allowlist
sub order_by($dbh, $column, $direction) {
my %allowed_cols = map { $_ => 1 } qw(name email created_at);
my %allowed_dirs = map { $_ => 1 } qw(ASC DESC);
die "Invalid column: $column\n" unless $allowed_cols{$column};
die "Invalid direction: $direction\n" unless $allowed_dirs{uc $direction};
my $sth = $dbh->prepare("SELECT * FROM users ORDER BY $column $direction");
$sth->execute;
return $sth->fetchall_arrayref({});
}
# Bad: Directly interpolating user-chosen column
sub bad_order($dbh, $column) {
$dbh->prepare("SELECT * FROM users ORDER BY $column"); # SQLi!
}
DBIx::Class (ORM Safety)
use v5.36;
# DBIx::Class generates safe parameterized queries
my @users = $schema->resultset('User')->search({
status => 'active',
email => { -like => '%@example.com' },
}, {
order_by => { -asc => 'name' },
rows => 50,
});
Web Security
XSS Prevention
use v5.36;
use HTML::Entities qw(encode_entities);
use URI::Escape qw(uri_escape_utf8);
# Good: Encode output for HTML context
sub safe_html($user_input) {
return encode_entities($user_input);
}
# Good: Encode for URL context
sub safe_url_param($value) {
return uri_escape_utf8($value);
}
# Good: Encode for JSON context
use JSON::MaybeXS qw(encode_json);
sub safe_json($data) {
return encode_json($data); # Handles escaping
}
# Template auto-escaping (Mojolicious)
# <%= $user_input %> — auto-escaped (safe)
# <%== $raw_html %> — raw output (dangerous, use only for trusted content)
# Template auto-escaping (Template Toolkit)
# [% user_input | html %] — explicit HTML encoding
# Bad: Raw output in HTML
sub bad_html($input) {
print "<div>$input</div>"; # XSS if $input contains <script>
}
CSRF Protection
use v5.36;
use Crypt::URandom qw(urandom);
use MIME::Base64 qw(encode_base64url);
sub generate_csrf_token() {
return encode_base64url(urandom(32));
}
Use constant-time comparison when verifying tokens. Most web frameworks (Mojolicious, Dancer2, Catalyst) provide built-in CSRF protection — prefer those over hand-rolled solutions.
Session and Header Security
use v5.36;
# Mojolicious session + headers
$app->secrets(['long-random-secret-rotated-regularly']);
$app->sessions->secure(1); # HTTPS only
$app->sessions->samesite('Lax');
$app->hook(after_dispatch => sub ($c) {
$c->res->headers->header('X-Content-Type-Options' => 'nosniff');
$c->res->headers->header('X-Frame-Options' => 'DENY');
$c->res->headers->header('Content-Security-Policy' => "default-src 'self'");
$c->res->headers->header('Strict-Transport-Security' => 'max-age=31536000; includeSubDomains');
});
Output Encoding
Always encode output for its context: HTML::Entities::encode_entities() for HTML, URI::Escape::uri_escape_utf8() for URLs, JSON::MaybeXS::encode_json() for JSON.
CPAN Module Security
- Pin versions in cpanfile:
requires 'DBI', '== 1.643'; - Prefer maintained modules: Check MetaCPAN for recent releases
- Minimize dependencies: Each dependency is an attack surface
Security Tooling
perlcritic Security Policies
# .perlcriticrc — security-focused configuration
severity = 3
theme = security + core
# Require checked system calls
[InputOutput::RequireCheckedSyscalls]
functions = :builtins
severity = 4
# Prohibit string eval
[BuiltinFunctions::ProhibitStringyEval]
severity = 5
# Prohibit backtick operators
[InputOutput::ProhibitBacktickOperators]
severity = 4
# Prohibit two-arg open
[InputOutput::ProhibitTwoArgOpen]
severity = 5
# Prohibit bare-word filehandles
[InputOutput::ProhibitBarewordFileHandles]
severity = 5
Running perlcritic
# Check a file
perlcritic --severity 3 --theme security lib/MyApp/Handler.pm
# Check entire project
perlcritic --severity 3 --theme security lib/
# CI integration
perlcritic --severity 4 --theme security --quiet lib/ || exit 1
Quick Security Checklist
| Check | What to Verify |
|---|---|
| Taint mode | -T flag on CGI/web scripts |
| Input validation | Allowlist patterns, length limits |
| File operations | Three-arg open, path traversal checks |
| Process execution | List-form system, no shell interpolation |
| SQL queries | DBI placeholders, never interpolate |
| HTML output | encode_entities(), template auto-escape |
| CSRF tokens | Generated, verified on state-changing requests |
| Session config | Secure, HttpOnly, SameSite cookies |
| HTTP headers | CSP, X-Frame-Options, HSTS |
| Dependencies | Pinned versions, audited modules |
| Regex safety | No nested quantifiers, anchored patterns |
| Error messages | No stack traces or paths leaked to users |
Anti-Patterns
# 1. Two-arg open with user data (command injection)
open my $fh, $user_input; # CRITICAL vulnerability
# 2. String-form system (shell injection)
system("convert $user_file output.png"); # CRITICAL vulnerability
# 3. SQL string interpolation
$dbh->do("DELETE FROM users WHERE id = $id"); # SQLi
# 4. eval with user input (code injection)
eval $user_code; # Remote code execution
# 5. Trusting $ENV without sanitizing
my $path = $ENV{UPLOAD_DIR}; # Could be manipulated
system("ls $path"); # Double vulnerability
# 6. Disabling taint without validation
($input) = $input =~ /(.*)/s; # Lazy untaint — defeats purpose
# 7. Raw user data in HTML
print "<div>Welcome, $username!</div>"; # XSS
# 8. Unvalidated redirects
print $cgi->redirect($user_url); # Open redirect
Remember: Perl's flexibility is powerful but requires discipline. Use taint mode for web-facing code, validate all input with allowlists, use DBI placeholders for every query, and encode all output for its context. Defense in depth — never rely on a single layer.
Perl Testing Patterns
Comprehensive testing strategies for Perl applications using Test2::V0, Test::More, prove, and TDD methodology.
When to Activate
- Writing new Perl code (follow TDD: red, green, refactor)
- Designing test suites for Perl modules or applications
- Reviewing Perl test coverage
- Setting up Perl testing infrastructure
- Migrating tests from Test::More to Test2::V0
- Debugging failing Perl tests
TDD Workflow
Always follow the RED-GREEN-REFACTOR cycle.
# Step 1: RED — Write a failing test
# t/unit/calculator.t
use v5.36;
use Test2::V0;
use lib 'lib';
use Calculator;
subtest 'addition' => sub {
my $calc = Calculator->new;
is($calc->add(2, 3), 5, 'adds two numbers');
is($calc->add(-1, 1), 0, 'handles negatives');
};
done_testing;
# Step 2: GREEN — Write minimal implementation
# lib/Calculator.pm
package Calculator;
use v5.36;
use Moo;
sub add($self, $a, $b) {
return $a + $b;
}
1;
# Step 3: REFACTOR — Improve while tests stay green
# Run: prove -lv t/unit/calculator.t
Test::More Fundamentals
The standard Perl testing module — widely used, ships with core.
Basic Assertions
use v5.36;
use Test::More;
# Plan upfront or use done_testing
# plan tests => 5; # Fixed plan (optional)
# Equality
is($result, 42, 'returns correct value');
isnt($result, 0, 'not zero');
# Boolean
ok($user->is_active, 'user is active');
ok(!$user->is_banned, 'user is not banned');
# Deep comparison
is_deeply(
$got,
{ name => 'Alice', roles => ['admin'] },
'returns expected structure'
);
# Pattern matching
like($error, qr/not found/i, 'error mentions not found');
unlike($output, qr/password/, 'output hides password');
# Type check
isa_ok($obj, 'MyApp::User');
can_ok($obj, 'save', 'delete');
done_testing;
SKIP and TODO
use v5.36;
use Test::More;
# Skip tests conditionally
SKIP: {
skip 'No database configured', 2 unless $ENV{TEST_DB};
my $db = connect_db();
ok($db->ping, 'database is reachable');
is($db->version, '15', 'correct PostgreSQL version');
}
# Mark expected failures
TODO: {
local $TODO = 'Caching not yet implemented';
is($cache->get('key'), 'value', 'cache returns value');
}
done_testing;
Test2::V0 Modern Framework
Test2::V0 is the modern replacement for Test::More — richer assertions, better diagnostics, and extensible.
Why Test2?
- Superior deep comparison with hash/array builders
- Better diagnostic output on failures
- Subtests with cleaner scoping
- Extensible via Test2::Tools::* plugins
- Backward-compatible with Test::More tests
Deep Comparison with Builders
use v5.36;
use Test2::V0;
# Hash builder — check partial structure
is(
$user->to_hash,
hash {
field name => 'Alice';
field email => match(qr/\@example\.com$/);
field age => validator(sub { $_ >= 18 });
# Ignore other fields
etc();
},
'user has expected fields'
);
# Array builder
is(
$result,
array {
item 'first';
item match(qr/^second/);
item DNE(); # Does Not Exist — verify no extra items
},
'result matches expected list'
);
# Bag — order-independent comparison
is(
$tags,
bag {
item 'perl';
item 'testing';
item 'tdd';
},
'has all required tags regardless of order'
);
Subtests
use v5.36;
use Test2::V0;
subtest 'User creation' => sub {
my $user = User->new(name => 'Alice', email => 'alice@example.com');
ok($user, 'user object created');
is($user->name, 'Alice', 'name is set');
is($user->email, 'alice@example.com', 'email is set');
};
subtest 'User validation' => sub {
my $warnings = warns {
User->new(name => '', email => 'bad');
};
ok($warnings, 'warns on invalid data');
};
done_testing;
Exception Testing with Test2
use v5.36;
use Test2::V0;
# Test that code dies
like(
dies { divide(10, 0) },
qr/Division by zero/,
'dies on division by zero'
);
# Test that code lives
ok(lives { divide(10, 2) }, 'division succeeds') or note($@);
# Combined pattern
subtest 'error handling' => sub {
ok(lives { parse_config('valid.json') }, 'valid config parses');
like(
dies { parse_config('missing.json') },
qr/Cannot open/,
'missing file dies with message'
);
};
done_testing;
Test Organization and prove
Directory Structure
t/
├── 00-load.t # Verify modules compile
├── 01-basic.t # Core functionality
├── unit/
│ ├── config.t # Unit tests by module
│ ├── user.t
│ └── util.t
├── integration/
│ ├── database.t
│ └── api.t
├── lib/
│ └── TestHelper.pm # Shared test utilities
└── fixtures/
├── config.json # Test data files
└── users.csv
prove Commands
# Run all tests
prove -l t/
# Verbose output
prove -lv t/
# Run specific test
prove -lv t/unit/user.t
# Recursive search
prove -lr t/
# Parallel execution (8 jobs)
prove -lr -j8 t/
# Run only failing tests from last run
prove -l --state=failed t/
# Colored output with timer
prove -l --color --timer t/
# TAP output for CI
prove -l --formatter TAP::Formatter::JUnit t/ > results.xml
.proverc Configuration
-l
--color
--timer
-r
-j4
--state=save
Fixtures and Setup/Teardown
Subtest Isolation
use v5.36;
use Test2::V0;
use File::Temp qw(tempdir);
use Path::Tiny;
subtest 'file processing' => sub {
# Setup
my $dir = tempdir(CLEANUP => 1);
my $file = path($dir, 'input.txt');
$file->spew_utf8("line1\nline2\nline3\n");
# Test
my $result = process_file("$file");
is($result->{line_count}, 3, 'counts lines');
# Teardown happens automatically (CLEANUP => 1)
};
Shared Test Helpers
Place reusable helpers in t/lib/TestHelper.pm and load with use lib 't/lib'. Export factory functions like create_test_db(), create_temp_dir(), and fixture_path() via Exporter.
Mocking
Test::MockModule
use v5.36;
use Test2::V0;
use Test::MockModule;
subtest 'mock external API' => sub {
my $mock = Test::MockModule->new('MyApp::API');
# Good: Mock returns controlled data
$mock->mock(fetch_user => sub ($self, $id) {
return { id => $id, name => 'Mock User', email => 'mock@test.com' };
});
my $api = MyApp::API->new;
my $user = $api->fetch_user(42);
is($user->{name}, 'Mock User', 'returns mocked user');
# Verify call count
my $call_count = 0;
$mock->mock(fetch_user => sub { $call_count++; return {} });
$api->fetch_user(1);
$api->fetch_user(2);
is($call_count, 2, 'fetch_user called twice');
# Mock is automatically restored when $mock goes out of scope
};
# Bad: Monkey-patching without restoration
# *MyApp::API::fetch_user = sub { ... }; # NEVER — leaks across tests
For lightweight mock objects, use Test::MockObject to create injectable test doubles with ->mock() and verify calls with ->called_ok().
Coverage with Devel::Cover
Running Coverage
# Basic coverage report
cover -test
# Or step by step
perl -MDevel::Cover -Ilib t/unit/user.t
cover
# HTML report
cover -report html
open cover_db/coverage.html
# Specific thresholds
cover -test -report text | grep 'Total'
# CI-friendly: fail under threshold
cover -test && cover -report text -select '^lib/' \
| perl -ne 'if (/Total.*?(\d+\.\d+)/) { exit 1 if $1 < 80 }'
Integration Testing
Use in-memory SQLite for database tests, mock HTTP::Tiny for API tests.
use v5.36;
use Test2::V0;
use DBI;
subtest 'database integration' => sub {
my $dbh = DBI->connect('dbi:SQLite:dbname=:memory:', '', '', {
RaiseError => 1,
});
$dbh->do('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
$dbh->prepare('INSERT INTO users (name) VALUES (?)')->execute('Alice');
my $row = $dbh->selectrow_hashref('SELECT * FROM users WHERE name = ?', undef, 'Alice');
is($row->{name}, 'Alice', 'inserted and retrieved user');
};
done_testing;
Best Practices
DO
- Follow TDD: Write tests before implementation (red-green-refactor)
- Use Test2::V0: Modern assertions, better diagnostics
- Use subtests: Group related assertions, isolate state
- Mock external dependencies: Network, database, file system
- Use
prove -l: Always include lib/ in@INC - Name tests clearly:
'user login with invalid password fails' - Test edge cases: Empty strings, undef, zero, boundary values
- Aim for 80%+ coverage: Focus on business logic paths
- Keep tests fast: Mock I/O, use in-memory databases
DON'T
- Don't test implementation: Test behavior and output, not internals
- Don't share state between subtests: Each subtest should be independent
- Don't skip
done_testing: Ensures all planned tests ran - Don't over-mock: Mock boundaries only, not the code under test
- Don't use
Test::Morefor new projects: Prefer Test2::V0 - Don't ignore test failures: All tests must pass before merge
- Don't test CPAN modules: Trust libraries to work correctly
- Don't write brittle tests: Avoid over-specific string matching
Quick Reference
| Task | Command / Pattern |
|---|---|
| Run all tests | prove -lr t/ |
| Run one test verbose | prove -lv t/unit/user.t |
| Parallel test run | prove -lr -j8 t/ |
| Coverage report | cover -test && cover -report html |
| Test equality | is($got, $expected, 'label') |
| Deep comparison | is($got, hash { field k => 'v'; etc() }, 'label') |
| Test exception | like(dies { ... }, qr/msg/, 'label') |
| Test no exception | ok(lives { ... }, 'label') |
| Mock a method | Test::MockModule->new('Pkg')->mock(m => sub { ... }) |
| Skip tests | SKIP: { skip 'reason', $count unless $cond; ... } |
| TODO tests | TODO: { local $TODO = 'reason'; ... } |
Common Pitfalls
Forgetting done_testing
# Bad: Test file runs but doesn't verify all tests executed
use Test2::V0;
is(1, 1, 'works');
# Missing done_testing — silent bugs if test code is skipped
# Good: Always end with done_testing
use Test2::V0;
is(1, 1, 'works');
done_testing;
Missing -l Flag
# Bad: Modules in lib/ not found
prove t/unit/user.t
# Can't locate MyApp/User.pm in @INC
# Good: Include lib/ in @INC
prove -l t/unit/user.t
Over-Mocking
Mock the dependency, not the code under test. If your test only verifies that a mock returns what you told it to, it tests nothing.
Test Pollution
Use my variables inside subtests — never our — to prevent state leaking between tests.
Remember: Tests are your safety net. Keep them fast, focused, and independent. Use Test2::V0 for new projects, prove for running, and Devel::Cover for accountability.
Rails Patterns
Framework patterns for modern Ruby on Rails applications (Rails 7.1+ and 8.x). Rails is opinionated by design; these are the patterns the community has converged on for apps that stay maintainable past the 50-model mark. This skill is the "how." For the "what" and "when" (the decisions about which pattern to reach for), see the Ruby patterns rules — rules/ruby/patterns.md in this repository, installed as rules/ecc/ruby/patterns.md.
When to Activate
- Building a Rails application (full-stack, API-only, or hybrid)
- Reviewing a PR that touches
app/orconfig/ - Generating models, controllers, services, or jobs
- A controller action grows past ~10 lines
- A model file grows past ~200 lines
- ActiveRecord queries start appearing in controllers or views
Core Concepts
The directory contract
Rails apps follow a predictable structure. Add directories deliberately, not casually.
app/
models/ ActiveRecord models. Persistence and domain logic close to the data.
controllers/ HTTP request handling. Thin orchestration only.
views/ ERB templates. No business logic.
components/ ViewComponent classes. View logic that needs tests.
services/ Service objects. Multi-step business operations.
forms/ Form objects. Complex form handling across multiple models.
queries/ Query objects. Reusable, composable ActiveRecord queries.
jobs/ Background jobs. Async work via Solid Queue, Sidekiq, or GoodJob.
mailers/ ActionMailer classes.
helpers/ View helpers. Tiny presentational logic only.
policies/ Authorization policies (if using Pundit). Optional.
channels/ ActionCable channels for WebSocket work.
Avoid app/lib/, app/utils/, app/managers/. If something does not fit the directories above, the design usually needs rethinking, not a new directory. Truly generic code goes in lib/.
Skinny controllers
Controllers receive a request, delegate to the right object, and render a response. Business logic lives elsewhere. (Per the Ruby patterns rules, extract to a service object when the controller starts carrying multiple responsibilities.)
Service objects
The default for business operations that touch more than a single model save. Conventions that keep them consistent:
- Namespace by domain (
Invoices::Create), not by suffix (InvoiceCreator). - A class method
.calldelegates to an instance#call. - Return a Result object, not a boolean or a bare record, so the caller can branch on success, errors, and the affected record.
- Wrap multi-record writes in a transaction.
- Keep each service single-purpose (
Invoices::Create,Invoices::MarkPaid), neverInvoices::Manager.
Form objects
When a form spans multiple models or has fields that do not map to columns, use a form object rather than nested attributes or virtual attributes on the wrong model. It quacks like a model to the view (form_with model: @form) while composing records cleanly.
Query objects
For ActiveRecord queries reused across controllers or services, or too complex for a scope, extract a query object that accepts a scope as input so it composes. Rule of thumb: a scope that grows past three chained conditions or starts taking parameters wants to be a query object.
Background jobs
Offload anything slow. (Per the Ruby patterns rules, Solid Queue for greenfield Rails 8 with modest throughput; Sidekiq when you need mature observability, high throughput, or existing Redis.) Regardless of adapter: pass IDs not records, make perform idempotent, and set retry_on/discard_on explicitly.
ViewComponent over partials
For view logic with conditional rendering, more than two arguments, or reuse across more than three places, prefer a ViewComponent. Components are testable in isolation and surface their interface explicitly; partials with deep conditional logic become debt.
Hotwire: Turbo and Stimulus
The default Rails frontend stack. (Per the Ruby patterns rules, prefer Hotwire for server-rendered apps; reach for React/Vue only when interaction complexity justifies the client surface.) Turbo Frames for partial page updates, Turbo Streams for server-driven updates, Stimulus for small client-side behaviors next to the markup.
The Rails 8 Solid stack
Rails 8 ships database-backed defaults that previously needed Redis: Solid Queue (jobs), Solid Cache (cache), Solid Cable (ActionCable). The tradeoff is more database load for one fewer infrastructure component; a good fit for modest throughput, with Redis still winning at high scale. Kamal is the default Docker-based deploy tool.
Code Examples
Skinny controller with a service object
# Bad: business logic in the controller
class InvoicesController < ApplicationController
def create
@invoice = Invoice.new(invoice_params)
@invoice.user = current_user
@invoice.line_items.build(invoice_params[:line_items])
@invoice.tax_total = TaxCalculator.new(@invoice).calculate
@invoice.total = @invoice.line_items.sum(&:amount) + @invoice.tax_total
if @invoice.save
InvoiceMailer.created(@invoice).deliver_later
AccountingExportJob.perform_later(@invoice.id)
redirect_to @invoice, notice: "Invoice created"
else
render :new
end
end
end
# Good: controller orchestrates, service does the work
class InvoicesController < ApplicationController
def create
result = Invoices::Create.call(params: invoice_params, user: current_user)
if result.success?
redirect_to result.invoice, notice: "Invoice created"
else
@invoice = result.invoice
render :new, status: :unprocessable_entity
end
end
end
The service object
# app/services/invoices/create.rb
module Invoices
class Create
# Struct keeps this runnable on every Ruby that Rails 7.1 supports.
# On Ruby 3.2+, `Data.define(:success?, :invoice, :errors)` is a more
# concise immutable alternative.
Result = Struct.new(:success, :invoice, :errors, keyword_init: true) do
def success?
success
end
end
def self.call(params:, user:)
new(params: params, user: user).call
end
def initialize(params:, user:)
@params = params
@user = user
end
def call
invoice = build_invoice
ApplicationRecord.transaction do
invoice.save!
end
begin
send_notifications(invoice)
rescue StandardError => e
Rails.logger.error("Notification dispatch failed for invoice #{invoice.id}: #{e.message}")
end
Result.new(success: true, invoice: invoice, errors: nil)
rescue ActiveRecord::RecordInvalid => e
Result.new(success: false, invoice: e.record, errors: e.record.errors)
end
private
attr_reader :params, :user
def build_invoice
invoice = user.invoices.new(params.except(:line_items))
invoice.line_items.build(params[:line_items])
invoice.tax_total = TaxCalculator.call(invoice)
invoice.total = invoice.line_items.sum(&:amount) + invoice.tax_total
invoice
end
def send_notifications(invoice)
InvoiceMailer.created(invoice).deliver_later
AccountingExportJob.perform_later(invoice.id)
end
end
end
Form object
# app/forms/signup_form.rb
class SignupForm
include ActiveModel::Model
include ActiveModel::Attributes
attribute :email, :string
attribute :password, :string
attribute :company_name, :string
attribute :terms_accepted, :boolean
validates :email, presence: true, format: URI::MailTo::EMAIL_REGEXP
validates :password, presence: true, length: { minimum: 12 }
validates :company_name, presence: true
validates :terms_accepted, acceptance: true
attr_reader :user, :company
def save
return false unless valid?
ApplicationRecord.transaction do
@company = Company.create!(name: company_name)
@user = @company.users.create!(email: email, password: password, role: :owner)
end
true
rescue ActiveRecord::RecordInvalid => e
errors.merge!(e.record.errors)
false
end
end
Query object
# app/queries/invoices/overdue.rb
module Invoices
class Overdue
def self.call(scope: Invoice.all, as_of: Time.current)
new(scope: scope, as_of: as_of).call
end
def initialize(scope:, as_of:)
@scope = scope
@as_of = as_of
end
def call
scope
.where(status: :sent)
.where(due_date: ..as_of)
.where.not(id: paid_invoice_ids)
.includes(:customer, :line_items)
end
private
attr_reader :scope, :as_of
def paid_invoice_ids
Payment.where(created_at: ..as_of).pluck(:invoice_id)
end
end
end
Query objects accept a scope, so they compose: Invoices::Overdue.call(scope: current_user.invoices).
N+1 prevention
# Bad: N+1 in the view when it calls post.author.name
@posts = Post.published
# Good: eager load
@posts = Post.published.includes(:author)
includes lets Rails choose preload vs eager_load. Force preload for separate queries, eager_load for a JOIN when filtering on the association. Since Rails 6.1, strict_loading raises on accidental lazy loads.
Counter cache
class Comment < ApplicationRecord
belongs_to :post, counter_cache: true
end
add_column :posts, :comments_count, :integer, default: 0, null: false
post.comments_count becomes a column read instead of a COUNT(*). This example
assumes a new table; adding a counter cache to a table that already has rows requires a
backfill, which is out of scope here.
Background job shape
Pass record IDs, not records. Retries make delivery at-least-once, so any job that calls an external service must be idempotent — otherwise a transient failure after the remote call succeeds will duplicate the effect on the next attempt.
class AccountingExportJob < ApplicationJob
queue_as :exports
retry_on AccountingApi::TransientError, wait: :polynomially_longer, attempts: 5
discard_on AccountingApi::PermanentError
def perform(invoice_id)
invoice = Invoice.find(invoice_id)
export = AccountingExport.create_or_find_by!(
invoice: invoice,
idempotency_key: "invoice-export-#{invoice.id}-#{invoice.updated_at.to_i}"
)
return if export.completed_at?
receipt = AccountingApi.export(invoice, idempotency_key: export.idempotency_key)
export.update!(completed_at: Time.current, external_id: receipt.id)
end
end
add_index :accounting_exports, :idempotency_key, unique: true
The unique index is what makes this safe: when two attempts race, the database rejects
the second insert and Active Record resolves the conflict inside the call, returning the
existing row. That happens without any job-level retry — retry_on above covers only
AccountingApi::TransientError. The guard
covers the window before the remote call; passing idempotency_key through to the API
covers the window after it, so a crash between the API call and update! still resolves
to a single export.
ViewComponent
# app/components/invoice_status_badge_component.rb
class InvoiceStatusBadgeComponent < ViewComponent::Base
STATUS_CLASSES = {
draft: "bg-gray-100 text-gray-800",
sent: "bg-blue-100 text-blue-800",
paid: "bg-green-100 text-green-800",
overdue: "bg-red-100 text-red-800"
}.freeze
def initialize(invoice:)
@invoice = invoice
end
def call
tag.span(@invoice.status.humanize, class: "rounded-full px-2 py-1 text-sm #{status_class}")
end
private
def status_class
STATUS_CLASSES.fetch(@invoice.status.to_sym, "bg-gray-100")
end
end
<%= render InvoiceStatusBadgeComponent.new(invoice: @invoice) %>
Hotwire
<%# Turbo Frame: clicking Edit replaces only this frame %>
<%= turbo_frame_tag "invoice_#{@invoice.id}" do %>
<div class="invoice">
<%= link_to "Edit", edit_invoice_path(@invoice) %>
</div>
<% end %>
<%# Turbo Stream: app/views/comments/create.turbo_stream.erb %>
<%= turbo_stream.append "comments", @comment %>
<%= turbo_stream.update "comment_form", partial: "form", locals: { comment: Comment.new } %>
// app/javascript/controllers/copy_to_clipboard_controller.js
import { Controller } from "@hotwired/stimulus"
export default class extends Controller {
static targets = ["source"]
copy() {
navigator.clipboard.writeText(this.sourceTarget.value)
}
}
Acceptable vs unacceptable callbacks
# Acceptable: pure data normalization
class User < ApplicationRecord
before_validation :normalize_email
private
def normalize_email
self.email = email.to_s.downcase.strip
end
end
# Move to a service instead: side effects hidden in a callback
# class User < ApplicationRecord
# after_create :send_welcome_email # hard to opt out of, hard to test
# end
Good concern vs bad concern
# Good: genuinely cross-cutting, reusable across unrelated models
# app/models/concerns/soft_deletable.rb
module SoftDeletable
extend ActiveSupport::Concern
included do
scope :active, -> { where(deleted_at: nil) }
scope :deleted, -> { where.not(deleted_at: nil) }
end
def soft_delete! = update!(deleted_at: Time.current)
def restore! = update!(deleted_at: nil)
end
# Bad: a "concern" used by exactly one model, holding logic that belongs on it
# app/models/concerns/invoice_calculations.rb
module InvoiceCalculations
extend ActiveSupport::Concern
def calculate_total
line_items.sum(&:amount) + tax_total
end
end
# Only Invoice includes this. It isn't cross-cutting; it's Invoice's own logic
# hidden in a module for the appearance of a "skinny" model. Put it back on Invoice.
A concern used by only one class is just moving code; it belongs in that class. A concern should be reusable across at least two unrelated models.
Anti-Patterns
God controllers
Any controller past ~80 lines is doing too much. Split actions across controllers or extract to services.
Fat models with 30+ methods
Models should know about their own data. Methods that orchestrate other models, send notifications, or coordinate workflows belong in services.
Callback chains
after_save :update_cache, :send_notifications, :enqueue_export is the start of a debugging nightmare. Move them into a service that runs them explicitly.
Nested attributes for complex forms
accepts_nested_attributes_for is fine for simple cases. For conditional validation or cross-model logic, use a form object.
Default scopes on critical models
default_scope { where(deleted: false) } silently excludes records from every query in the app, including the ones you need for support and debugging. Prefer an explicit named scope.
Models named after database concepts
UserRole, OrderStatus, InvoiceState are usually enum candidates, not models.
Reaching for a JS framework before Hotwire
If the page is server-rendered with occasional interactivity, Hotwire ships faster. Reserve React/Vue for genuinely SPA-shaped apps.
Best Practices
- Keep controllers thin; push business logic into services.
- Return Result objects from services so callers branch on outcome, not exceptions.
- Wrap multi-record writes in a transaction; let notification/side-effect failures log without breaking the primary write.
- Pass IDs to jobs, keep
performidempotent, set retry/discard explicitly. - Default to eager loading; treat an accidental N+1 as a bug, not a nuisance.
- Reserve concerns for behavior shared across at least two unrelated models.
- Reach for Hotwire before a client-side framework on server-rendered apps.
Related Skills
backend-patterns— service boundaries and adapter patterns (referenced by the Ruby patterns rules)- Ruby patterns rules (
rules/ruby/patterns.md, installed asrules/ecc/ruby/patterns.md) — the decisions and when-to-use guidance this skill implements
ShellCheck Configuration and Static Analysis
Comprehensive guidance for configuring and using ShellCheck to improve shell script quality, catch common pitfalls, and enforce best practices through static code analysis.
When to Use This Skill
- Setting up linting for shell scripts in CI/CD pipelines
- Analyzing existing shell scripts for issues
- Understanding ShellCheck error codes and warnings
- Configuring ShellCheck for specific project requirements
- Integrating ShellCheck into development workflows
- Suppressing false positives and configuring rule sets
- Enforcing consistent code quality standards
- Migrating scripts to meet quality gates
Detailed patterns and worked examples
Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.
Best Practices
- Run ShellCheck in CI/CD - Catch issues before merging
- Configure for your target shell - Don't analyze bash as sh
- Document exclusions - Explain why violations are suppressed
- Address violations - Don't just disable warnings
- Enable strict mode - Use
--enable=allwith careful exclusions - Update regularly - Keep ShellCheck current for new checks
- Use pre-commit hooks - Catch issues locally before pushing
- Integrate with editors - Get real-time feedback during development
Writing Lean Proofs
Contents
- When to Use
- When NOT to Use
- The workflow
- The extraction ladder
- Quick reference
- Rationalizations to reject
- References
Structured Lean 4 proof writing and library design, distilled from Mathlib's style and review conventions and from the methodology of large formalization projects (Liquid Tensor Experiment, PFR, Fermat's Last Theorem).
Core principle: design top-down, prove bottom-up. Lean propositions are
proof-irrelevant — only a theorem's statement can affect later declarations.
Statements are the stable interface; proofs are disposable and freely
replaceable. Put design effort into definitions and statements, then fill in
proofs against skeletons that already compile (modulo sorry).
When to Use
- Proving theorems in Lean 4, from single lemmas to multi-file developments
- Formalizing mathematics, protocols, or software specifications in Lean
- Defining new types, structures, or functions in a Lean library
- Reviewing Lean code for readability, maintainability, or Mathlib readiness
- Refactoring a long or fragile tactic proof into lemmas
- Setting up a formalization project that several people or agents will contribute to in parallel
- Setting up CI, linters, or verification gates for a Lean project — do this at project start, before patterns propagate
- Diagnosing slow proofs,
maxHeartbeatstimeouts, or expensive reduction - Writing custom tactics, macros, or project-specific linters
When NOT to Use
- Lean 4 as a general-purpose programming language (no proofs involved) — most of this skill targets proof and API structure
- Coq, Isabelle, Agda, or Lean 3 — conventions and tactic names differ;
Lean 3 idioms (
ge_or_gtlinting,discrete_field) are obsolete - Verified-software Lean projects with their own house style (e.g. spec-traceability-first codebases): Mathlib conventions are the community default, but check the project's CONTRIBUTING first and defer to it
The workflow
1. Design definitions and their API first
Definitions carry the design weight. Before proving anything about a new concept:
- Prefer total functions with junk values over subtypes or
Optionin signatures (Mathlib:(0 : ℝ)⁻¹ = 0). Side conditions then appear only on the lemmas that need them, not at every use site. - Bundle: new morphism kinds are structures with a
FunLikeinstance; new subobject kinds useSetLike; carry property proofs as structure fields, not separateIsHom-style predicates. - Pick the canonical spelling (simp-normal form) for every concept with multiple equivalent forms, and state all API lemmas for that form only.
- Write the API in the same file, immediately:
ext,@[simp], coercion, and injectivity lemmas — before the definition is used anywhere. Downstream proofs use the API, neverunfold/show ... from rfl.
See library-design.md for the full set of design rules with rationale.
2. Build a sorry skeleton
State everything before proving anything, at every scale:
- Project scale: state the target theorem and the lemmas it needs, all
with
:= sorry, and make the file compile. Eachsorryis now an independent work unit — a contributor (human or LLM) can discharge one without understanding the rest. This is how LTE, PFR, and FLT scale to dozens of parallel contributors. - Proof scale: inside a proof, lay out the
have/suffices/calcskeleton withsorryjustifications, get Lean to accept the structure, then fill each step. Keeping the structure intact is what produces useful error messages while you work.
example (a b c d : ℝ) (h : c = d * a + b) (h' : b = a * d) : c = 2 * a * d := by
calc
c = d * a + b := sorry
_ = d * a + a * d := sorry
_ = 2 * a * d := sorry
3. Fill goals, one focused goal at a time
- Every new subgoal gets a focusing dot
·with an indented block — never leave several goals active in unfocused sequence (Mathlib'smultiGoallinter enforces this). This is what kills fragile goal-ordering dependence. - Open each block with a redundant
showstating its goal. The proof works without it; reviewers and future editors need it. Ifshowwould change the goal, usechangeinstead — keep stated goals honest. - Chained rewrites of (in)equalities become
calcblocks, relations aligned vertically. havefor forward stepping stones ("we first establish X");sufficesfor backward reduction ("it suffices to show X").- While drafting, annotate the goal state as a comment before non-obvious
tactics — emitted by Lean, never imagined. In a headless workflow, insert
trace_stateat the point of interest or a deliberatedonewhere goals should be closed, then runlake env lean Path/To/File.lean; copy the reported hypotheses, case name, and target. Strip routine probes after the proof works. This is the single most effective technique for LLM-written proofs (see llm-techniques.md).
See proof-style.md for the full tactic-style rules, and naming-conventions.md for naming lemmas so their names are guessable from their statements.
4. Verify mechanically
Do not eyeball-check style — run the checkers. lake build is the floor,
and it is only the floor: sorry is a warning, so a green build exits 0
with sorries still present.
- Gate unproved obligations by asking the kernel, never by grepping.
#print axioms myTheoremfor a spot check; for CI, collect axioms per declaration withLean.collectAxiomsand assert the whole expected footprint ([propext, Classical.choice, Quot.sound]unless deliberately widened), so a straysorryor a new trust assumption likenative_decidefails loudly. Grep is wrong in both directions: it matches the word in comments, and it misses a theorem whose own text is clean but which applies an unproved helper. Working script in linting.md. - Choose lints by project role and put them in CI at project start. Do not
enable
linter.mathlibStandardSetwholesale in a downstream project: it combines proof-maintenance checks with public-API checks, house style, and Mathlib-specific repository policy. For a self-contained proof, start withlinter.auxLemma,linter.style.maxHeartbeats,linter.style.multiGoal,linter.style.setOption, andlinter.style.show. A reusable library should additionally enablelinter.flexible,linter.style.missingEnd,linter.style.openClassical, and the twounused*InTypechecks. TreatnativeDecideas a trust-policy choice and formatting or deprecated-syntax checks as project style. No warning gates anything unless warnings fail the build. Run Batteries' declaration-level#lintchecks, includingsimpNF, separately. Verify every option against the pinned Mathlib source and with a known-trigger fixture: a misspelledweak.option is intentionally ignored. The complete 26-member audit and lakefile profiles are in linting.md. - Write a custom linter for every project-specific convention (simp-set
discipline, summary-lemma coverage, required attributes) — a
declaration-level
@[env_linter]is one structure, and it is the only thing that reliably catches "the attribute is missing on 29 of 30 declarations". See linting.md for the recipe and the engineering rules (vacuity anchors, prove-it-can-fail, allowlists).
The extraction ladder
When does proof structure graduate into separate lemmas?
-
Before extracting, state the fragment's type and search by shape. Put the proposed statement in a scratch
example, runexact?andapply?on the bare goal, then try a type-pattern and source search. If an existing theorem fits, use it. Do not report an API gap without recording the searches that failed. -
A sub-argument repeats within one proof → name it as a local
have.theorem min_comm (a b : ℝ) : min a b = min b a := by have h : ∀ x y : ℝ, min x y ≤ min y x := by intro x y apply le_min · show min x y ≤ y exact min_le_right x y · show min x y ≤ x exact min_le_left x y apply le_antisymm · show min a b ≤ min b a exact h a b · show min b a ≤ min a b exact h b a -
The statement is independently interesting, or extraction sheds hypotheses the sub-argument does not need → standalone lemma. Dropping unneeded hypotheses is the stronger trigger: the extracted lemma becomes more general than the proof it came from.
-
The proof reads as "long and unwieldy" → split it. This is Mathlib's review criterion, and it is deliberately qualitative — there is no line threshold. Resolve doubt by attempting the extraction: if a fragment has a clean statement, it wanted to be a lemma.
Quick reference
| Rule | Why | Enforced by |
|---|---|---|
Never unfold definitions downstream; erw or trailing rfl = missing API | API lemmas are the abstraction boundary | review ("missing API" smell) |
Terminal simp stays unsqueezed; non-terminal simp becomes simp only [...] | squeezed terminal calls bury the key lemmas and break on renames | style guide |
One focused goal at a time (· blocks) | kills goal-ordering fragility | linter.style.multiGoal |
show must not change the goal (use change) | stated goals stay honest | linter.style.show |
No set_option debug/trace/profiler or unscoped maxHeartbeats in final code | debugging scaffolding | linter.style.setOption |
State lemmas in simp-normal form, < not > | simp matches syntactically | simpNF linter |
| Golf only when the result is at least as readable; trivial results exempt | short ≠ better | review |
Fact instances are local, never global | global instances degrade all typeclass search | review |
| Name lemmas from their statements (see naming reference) | names become guessable without search | linter.style.nameCheck catches only __; #lint defsWithUnderscore and review cover more |
| Search a bare goal by shape before writing a helper or claiming an API gap | names are not always guessable from the target | exact?, apply?, type/source search |
| Generally one tactic invocation per line; a one-line closing proof is the exception | preserves readable proof structure without inventing an absolute rule | style guide |
Gate sorry with collectAxioms/#print axioms, never grep | grep matches comments, misses unproved helpers | axiom audit in CI |
| Prefer simp-lemma LHSs keyed on structure, not numerals; one spelling per constant | 2 ^ 32 never matches a goal normalized to 4294967296 | simpNF, review |
Re-derive every simp only list with simp? at its own site | lists do not transfer between look-alike goals | linter.flexible |
Every maxHeartbeats override is an unproven claim — measure before believing | copy-pasted budgets carry no information | #count_heartbeats, bisection |
Conditional simp lemma fires shallow but not deep → raise maxDischargeDepth (default 2) | chained side conditions truncate silently, no diagnostic | diagnosis (proof-style, simp discipline) |
| Every project-specific convention gets a custom linter, in CI from day one | review misses the 29-of-30 failure mode | @[env_linter] + #lint |
Full rationale for each row, plus the library-level anti-patterns, in anti-patterns.md.
Rationalizations to reject
| Excuse | Reality |
|---|---|
| "The proof compiles, ship it" | Compiling is the floor. A monolithic tactic block that only Lean can read will break silently at the next Mathlib bump and no one will be able to repair it. |
| "Unfolding the definition is simpler than writing API lemmas" | Every downstream unfold couples a proof to the implementation. The first refactor breaks all of them at once. Write the missing lemma. |
| "Squeezing every simp makes the proof faster and more robust" | Backwards for terminal simp calls: the squeezed list breaks on every rename and drowns the signal. Squeeze non-terminal calls only. |
| "It's shorter, therefore better" | Mathlib review policy: golfing is fine only when it does not sacrifice readability. Length is not the target; legibility is. |
| "I'll restructure it into lemmas after it works" | After it works, the structure is load-bearing and tangled. State the skeleton first; the lemmas fall out for free. |
"Adding show lines is redundant noise" | They are redundant to the kernel and essential to every human or model that reads the proof next. |
| "This helper is too specific to be a lemma" | If it has a clean statement, extract it — dropping the hypotheses it doesn't need usually reveals it was general all along. |
| "We'll add linters once the library stabilizes" | Backwards: patterns propagate by copy-paste, so a deferred linter meets a 400-warning backlog instead of one bad line. Enable what is already clean and gate it now. |
| "The check passed, so we're clean" | A check that can't fail proves nothing — sweeps reach zero files, misspelled weak. options are ignored, pipelines swallow exit codes. Prove every gate can fail before trusting that it passes. |
| "The proof is slow, raise maxHeartbeats" | An unmeasured budget is a claim, not a fix — and it masks the regression the next reader needs to see. Measure with #count_heartbeats; restructure the definition or decompose the goal. |
References
- library-design.md — definitions, APIs, bundling, abstraction boundaries, spec-driven project decomposition
- proof-style.md — tactic proof structure: calc, have/suffices, focusing, and simp discipline including the why-doesn't-this-lemma-fire diagnoses (discharge depth, traversal order, numeral spellings)
- naming-conventions.md — Mathlib naming so lemma names are computable from statements
- anti-patterns.md — recognized anti-patterns, why each is harmful, and which linter catches it
- llm-techniques.md — evidence-based techniques specific to LLM-written proofs
- linting.md — axiom-based sorry gates, enabling project-specific linter profiles in CI early, the full Mathlib standard-set audit, adopting linters with a backlog, writing custom linters for project-specific constructs, and proving every gate can fail
- performance.md — measuring per-declaration cost, where reduction cost comes from, optimizing definitions without losing semantics
- tactics.md — metaprogramming discipline: extension-point selection, metavariable and recovery safeguards, bounded search, actionable errors, structured tracing, generated declarations, and failure-surface testing
Sponsors
Details
- Marketplace
- marslanalvi/SkillsStack
- Source
- plugins/engineering/other-languages
- Category
- Engineering
- Keywords
- engineering, other-languages
More from marslanalvi/SkillsStack
All 45- engineering-pythonv1.0.0
- engineering-systems-languagesv1.0.0
- engineering-testingv1.0.0
- marketing-content-socialv1.0.0
- marketing-growth-adsv1.0.0
- marketing-seov1.0.0
- productivity-automation-personalv1.0.0
- productivity-documents-officev1.0.0
- productivity-thinking-planningv1.0.0
- productivity-writing-communicationv1.0.0
- security-appsec-reviewv1.0.0
- security-blockchain-web3v1.0.0
- security-compliance-privacyv1.0.0
- security-fuzzingv1.0.0
- security-offensive-securityv1.0.0
- ai-agent-engineeringv1.0.0
- ai-coding-assistant-workflowv1.0.0
- ai-llm-applicationsv1.0.0
- ai-machine-learningv1.0.0
- ai-skill-authoringv1.0.0
- business-legal-industryv1.0.0
- business-operations-financev1.0.0
- business-strategy-salesv1.0.0
- data-data-engineering-analyticsv1.0.0